diff --git a/.planning/STATE.md b/.planning/STATE.md index 427494a..1344c7d 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -28,7 +28,7 @@ See: .planning/PROJECT.md (updated 2026-03-29) Phase: 04 Plan: Not started Status: Phase complete — ready for verification -Last activity: 2026-03-29 +Last activity: 2026-03-29 - Completed quick task 260329-ten: Leertaste-Symbol in Entdecken-Phase erklären Progress: [░░░░░░░░░░] 0% @@ -120,6 +120,12 @@ None yet. None yet. +### Quick Tasks Completed + +| # | Description | Date | Commit | Directory | +|---|-------------|------|--------|-----------| +| 260329-ten | Leertaste-Symbol in Entdecken-Phase erklären | 2026-03-29 | a7afe06 | [260329-ten-leertaste-symbol-in-entdecken-phase-erkl](./quick/260329-ten-leertaste-symbol-in-entdecken-phase-erkl/) | + ## Session Continuity Last session: 2026-03-29T16:23:36.950Z diff --git a/.planning/quick/260329-ten-leertaste-symbol-in-entdecken-phase-erkl/260329-ten-PLAN.md b/.planning/quick/260329-ten-leertaste-symbol-in-entdecken-phase-erkl/260329-ten-PLAN.md new file mode 100644 index 0000000..e15d482 --- /dev/null +++ b/.planning/quick/260329-ten-leertaste-symbol-in-entdecken-phase-erkl/260329-ten-PLAN.md @@ -0,0 +1,163 @@ +--- +phase: quick +plan: 260329-ten +type: execute +wave: 1 +depends_on: [] +files_modified: + - src/ui/screens.ts +autonomous: true +must_haves: + truths: + - "Space bar is explained in the discover phase of level 1 before practice begins" + - "The ␣ symbol is shown and named so the child knows what it means in practice" + - "The child must press the space bar once during discover to confirm understanding" + artifacts: + - path: "src/ui/screens.ts" + provides: "Space bar discover step in runDiscoverPhase" + contains: "Leertaste" + key_links: + - from: "src/ui/screens.ts runDiscoverPhase" + to: "src/ui/screens.ts runLetterExercise" + via: "space symbol ␣ introduced in discover, then used in practice" + pattern: "\\u2423" +--- + + +Show and explain the space bar (Leertaste) and its symbol ␣ during the discover phase of level 1, so the child understands what the symbol means before encountering it in practice. + +Purpose: Currently `runDiscoverPhase()` skips space entirely (`if (key === " ") continue`). During practice, space appears as the ␣ symbol (U+2423), but the child has never seen this symbol explained. This is confusing for a 7-year-old. + +Output: Modified discover phase that includes a special step for the space bar. + + + +@.planning/quick/260329-ten-leertaste-symbol-in-entdecken-phase-erkl/260329-ten-PLAN.md + + + +@src/ui/screens.ts (main file to modify — discover phase at ~line 356-422) +@src/companion/fallbacks.ts (has existing space fallback text at line 98-101) +@src/companion/companion.ts (getLetterIntro function — generates intro text via AI or fallback) +@src/game/keyboard.ts (space key rendering — line 93, 101) + + + + + + Task 1: Add space bar discover step in runDiscoverPhase + src/ui/screens.ts + +In `runDiscoverPhase()` (around line 361-417), replace the space-skipping logic with a dedicated space discover step. + +Current code (line 363): +``` +if (key === " ") continue; // Skip space in discover +``` + +Replace with a special branch for space that: + +1. Instead of `continue`, check `if (key === " ")` and handle it specially (do NOT skip it). + +2. For the companion text: call `getLetterIntro(characterType, "LEERTASTE", fingerDescriptions[" "]!, db)` — but note the AI prompt uses the letter parameter as the key name. Since the existing fallback and AI both work with letter=" ", pass " " as the letter. However, the fallback text (line 98-101 in fallbacks.ts) already has a good explanation: "Die grosse Leertaste ganz unten drueckst du mit dem Daumen. Einfach druecken!" + + Actually, to keep it simple and avoid the AI generating something that doesn't mention the ␣ symbol, use a hardcoded intro text instead of calling getLetterIntro. Set: + ```typescript + companionText.textContent = "Siehst du die grosse Taste ganz unten? Das ist die Leertaste! Wenn du dieses Zeichen siehst: ␣ — dann drueckst du mit dem Daumen die Leertaste. Probier es aus!"; + ``` + +3. For the letter display area, show the ␣ symbol large (same as other letters use the `falling-letter` class), and add a small label underneath: + ```typescript + letterArea.innerHTML = ""; + const letterEl = document.createElement("div"); + letterEl.className = "falling-letter"; + letterEl.textContent = "\u2423"; // ␣ symbol + letterArea.appendChild(letterEl); + const labelEl = document.createElement("div"); + labelEl.style.cssText = "text-align: center; font-size: 1.2rem; color: var(--text-secondary, #666); margin-top: 0.5rem; font-family: 'Quicksand', sans-serif;"; + labelEl.textContent = "Leertaste"; + letterArea.appendChild(labelEl); + ``` + +4. Highlight and pulse the space key on the keyboard (same as other keys): + ```typescript + highlightKey(" "); + const keyEl = document.querySelector('[data-key=" "]') as HTMLElement | null; + if (keyEl) { + keyEl.classList.add("keyboard__key--discover-pulse"); + } + ``` + +5. Wait for the child to press the space bar (same pattern as other keys): + ```typescript + await new Promise((resolve) => { + function onKeyDown(e: KeyboardEvent): void { + if (e.key !== " ") return; + e.preventDefault(); + pressKey(e.key); + document.removeEventListener("keydown", onKeyDown); + activeKeyDown = null; + if (keyEl) { + keyEl.classList.remove("keyboard__key--discover-pulse"); + } + resolve(); + } + if (activeKeyDown) { + document.removeEventListener("keydown", activeKeyDown); + } + activeKeyDown = onKeyDown; + document.addEventListener("keydown", onKeyDown); + }); + ``` + +6. After the await, do NOT clear letterArea/companionText here — let the normal loop cleanup at end of function handle it (or the next iteration). Actually, the normal flow after the for-loop clears these on lines 420-421, so this is fine. + +Important: Keep the space handling INSIDE the for-loop, as a special branch. The structure should be: +```typescript +for (const key of levelDef.newKeys) { + if (cancelled) return; + + if (key === " ") { + // Special space bar discover step (code from above) + // ... show companion text, show ␣ symbol, highlight key, wait for press + continue; + } + + // Existing letter discover code stays unchanged + const fingerDesc = fingerDescriptions[key] || "ein Finger"; + // ... rest of existing code +} +``` + +This way the space is processed BEFORE the continue, shown to the child, and then the loop continues to clean up naturally. + + + cd /home/dev/workspace/zauberwald && npx vitest run --reporter=verbose 2>&1 | tail -20 + + + - Level 1 discover phase no longer skips space + - Space bar step shows the ␣ symbol with "Leertaste" label underneath + - Companion explains what the symbol means in child-friendly German + - Space key pulses on keyboard during the discover step + - Child must press space bar to continue + - All existing tests still pass + + + + + + +1. Run existing tests: `npx vitest run` — all pass +2. Manual: Start level 1 lesson. In the discover phase, after F and J are introduced, the space bar step should appear showing ␣ with explanation text. Pressing space advances past it. +3. In the following practice phase, when ␣ appears as a target, the child already knows what it means. + + + +- The ␣ symbol and "Leertaste" concept are introduced in the discover phase before they appear in practice +- The discover step follows the same UX pattern as letter discover steps (companion text + visual + keyboard highlight + press to confirm) +- No regressions in existing tests + + + +After completion, create `.planning/quick/260329-ten-leertaste-symbol-in-entdecken-phase-erkl/260329-ten-SUMMARY.md` +