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

phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	must_haves
quick	260329-ten	execute	1		src/ui/screens.ts	true	truths artifacts key_links 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 path provides contains src/ui/screens.ts Space bar discover step in runDiscoverPhase Leertaste from to via pattern src/ui/screens.ts runDiscoverPhase src/ui/screens.ts runLetterExercise space symbol ␣ introduced in discover, then used in practice \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.

<execution_context> @.planning/quick/260329-ten-leertaste-symbol-in-entdecken-phase-erkl/260329-ten-PLAN.md </execution_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) 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:

   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:

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

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

   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:

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.

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

After completion, create `.planning/quick/260329-ten-leertaste-symbol-in-entdecken-phase-erkl/260329-ten-SUMMARY.md`