docs(quick-260329-ten): Leertaste-Symbol in Entdecken-Phase erklären

.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

.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"
+---
+
+<objective>
+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.
+</objective>
+
+<execution_context>
+@.planning/quick/260329-ten-leertaste-symbol-in-entdecken-phase-erkl/260329-ten-PLAN.md
+</execution_context>
+
+<context>
+@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)
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add space bar discover step in runDiscoverPhase</name>
+  <files>src/ui/screens.ts</files>
+  <action>
+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<void>((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.
+  </action>
+  <verify>
+    <automated>cd /home/dev/workspace/zauberwald && npx vitest run --reporter=verbose 2>&1 | tail -20</automated>
+  </verify>
+  <done>
+    - 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
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+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.
+</verification>
+
+<success_criteria>
+- 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
+</success_criteria>
+
+<output>
+After completion, create `.planning/quick/260329-ten-leertaste-symbol-in-entdecken-phase-erkl/260329-ten-SUMMARY.md`
+</output>