Zauberwald/.planning/quick/260329-ten-leertaste-symbol-in-entdecken-phase-erkl/260329-ten-PLAN.md

---
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>