docs(quick-260329-ten): Leertaste-Symbol in Entdecken-Phase erklären
This commit is contained in:
+163
@@ -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>
|
||||
Reference in New Issue
Block a user