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