Zauberwald/.planning/phases/04-polish-audio/04-04-PLAN.md

---
phase: 04-polish-audio
plan: 04
type: execute
wave: 2
depends_on: ["04-01", "04-02", "04-03"]
files_modified:
  - src/ui/screens.ts
  - src/forest/reward.ts
  - src/forest/scene.ts
  - src/app.ts
autonomous: false

requirements: [PLSH-01, PLSH-02, PLSH-03, PLSH-04, PLSH-05, AUDI-01, AUDI-02, AUDI-03, AUDI-04, AUDI-05, PRNT-05, PRNT-06, PRNT-07]

must_haves:
  truths:
    - "Richtiger Tastendruck in lesson spielt kurzen Ton"
    - "Belohnungs-Screen spielt aufsteigende Tonfolge"
    - "Neues Waldelement in Forest spielt Glitzer-Sound"
    - "Companion-Texte werden vorgelesen wenn speechEnabled=true"
    - "Gesamte App funktioniert fehlerfrei als zusammenhaengendes Erlebnis"
  artifacts:
    - path: "src/ui/screens.ts"
      provides: "playCorrectSound() call on correct keypress"
      contains: "playCorrectSound"
    - path: "src/forest/reward.ts"
      provides: "playRewardSound() + speakText() calls"
      contains: "playRewardSound"
    - path: "src/forest/scene.ts"
      provides: "playForestElementSound() on new element"
      contains: "playForestElementSound"
  key_links:
    - from: "src/ui/screens.ts"
      to: "src/audio/sounds.ts"
      via: "import + call in correct keypress handler"
      pattern: "import.*playCorrectSound"
    - from: "src/forest/reward.ts"
      to: "src/audio/sounds.ts"
      via: "import + call in reward init"
      pattern: "import.*playRewardSound"
    - from: "src/forest/scene.ts"
      to: "src/audio/sounds.ts"
      via: "import + call on element appear"
      pattern: "import.*playForestElementSound"
    - from: "src/forest/reward.ts"
      to: "src/audio/speech.ts"
      via: "import + speakText for companion comment"
      pattern: "import.*speakText"
---

<objective>
Wire audio into all touch points and verify the complete Phase 4 experience end-to-end.

Purpose: Connect the audio system (Plan 01), animations (Plan 02), and export/import (Plan 03) into a cohesive experience. Human verification confirms everything works together.
Output: Fully wired audio in lesson/reward/forest, human-verified complete app.
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/04-polish-audio/04-CONTEXT.md
@.planning/phases/04-polish-audio/04-01-SUMMARY.md
@.planning/phases/04-polish-audio/04-02-SUMMARY.md
@.planning/phases/04-polish-audio/04-03-SUMMARY.md

@src/ui/screens.ts
@src/forest/reward.ts
@src/forest/scene.ts
@src/app.ts
@src/audio/sounds.ts
@src/audio/speech.ts
</context>

<tasks>

<task type="auto">
  <name>Task 1: Wire audio + speech into lesson, reward, forest, and app</name>
  <files>src/ui/screens.ts, src/forest/reward.ts, src/forest/scene.ts, src/app.ts</files>
  <read_first>src/ui/screens.ts, src/forest/reward.ts, src/forest/scene.ts, src/app.ts, src/audio/sounds.ts, src/audio/speech.ts</read_first>
  <action>
1. In `src/ui/screens.ts` (per AUDI-01):
   - Import `playCorrectSound` from `../audio/sounds`
   - In the keydown handler where `result.correct` is true (two locations: letter mode ~line 214, word mode ~line 289), add `playCorrectSound()` call. Fire-and-forget (no await needed, sound functions handle errors internally).

2. In `src/forest/reward.ts` (per AUDI-02, AUDI-05):
   - Import `playRewardSound` from `../audio/sounds`
   - Import `speakText` from `../audio/speech`
   - In `initRewardScreen` (or wherever the reward is displayed), call `playRewardSound()` when the reward image/content appears.
   - After companion comment text is set, call `speakText(commentText)` to read it aloud.

3. In `src/forest/scene.ts` (per AUDI-03):
   - Import `playForestElementSound` from `../audio/sounds`
   - When a new forest element is rendered/appears (the element with `forest-element-appear` animation), call `playForestElementSound()`.

4. In `src/app.ts` (per AUDI-05):
   - Import `speakText` from `../audio/speech`
   - Where the companion greeting text is displayed on the forest screen, call `speakText(greetingText)` to read it aloud.

All audio calls are fire-and-forget. The sound/speech modules internally check settings and handle errors. No try/catch needed at call sites.
  </action>
  <verify>
    <automated>cd /home/dev/workspace/zauberwald && npx tsc --noEmit 2>&1 | head -20 && grep -c "playCorrectSound\|playRewardSound\|playForestElementSound\|speakText" src/ui/screens.ts src/forest/reward.ts src/forest/scene.ts src/app.ts</automated>
  </verify>
  <acceptance_criteria>
    - screens.ts imports and calls playCorrectSound on correct keypress
    - reward.ts imports and calls playRewardSound when reward displays
    - reward.ts imports and calls speakText for companion comment
    - scene.ts imports and calls playForestElementSound on new element
    - app.ts imports and calls speakText for greeting
    - TypeScript compiles without errors
  </acceptance_criteria>
  <done>All audio touch points wired: correct keystroke sound, reward melody, forest element glitter, speech for companion texts</done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 2: End-to-end verification of Phase 4</name>
  <files>none</files>
  <action>Human verifies the complete Phase 4 experience by testing all audio, animation, responsive, error handling, and export/import/reset features in the browser.</action>
  <what-built>
Complete Phase 4 polish: audio system (3 sounds + speech), enhanced animations (leaf-fall, stardust, companion float), responsive layout, error handler, export/import/reset.
  </what-built>
  <how-to-verify>
Start the dev server: `npm run dev`

Open http://&lt;vps-ip&gt;:5173 in browser.

**1. Audio (AUDI-01..03):**
- Start a lesson, type correct letters -- hear short tone on each correct press
- Complete a lesson -- hear ascending reward melody on reward screen
- Go back to forest -- hear glitter sound when new element appears
- If no sound: check mute button state

**2. Mute Button (AUDI-04):**
- Click mute button (bottom-right) -- icon changes to muted
- Type correct letters -- no sound
- Reload page -- mute state preserved
- Click again -- unmuted, sounds resume

**3. Speech (AUDI-05):**
- Enable speech in parent area settings (if toggle exists) or check if companion texts are read aloud
- Greeting on forest screen should be spoken in German

**4. Animations (PLSH-01..03):**
- Falling letters sway side-to-side like leaves (not just float up/down)
- Correct keypress shows sparkle/stardust particles
- Companion avatar gently bobs up and down

**5. Responsive (PLSH-04):**
- Resize browser to < 700px width -- keyboard shrinks, fonts scale, grid adjusts

**6. Error Handler (PLSH-05):**
- Open console, run: `throw new Error('test')` -- child-friendly overlay appears
- Click "Nochmal versuchen" -- page reloads

**7. Export/Import/Reset (PRNT-05..07):**
- Open parent area (Ctrl+Shift+E, code 1234)
- Click "Fortschritt exportieren" -- JSON file downloads
- Click "Fortschritt importieren" -- file picker opens, select the exported file, confirm
- Click "Alles zuruecksetzen" -- two confirmations, then app resets to welcome screen

**8. No console errors:**
- Play through a complete lesson cycle with console open -- no unhandled errors
  </how-to-verify>
  <verify>Human confirms all 8 verification areas pass</verify>
  <done>All Phase 4 features verified: audio plays at correct moments, mute persists, animations smooth, responsive works, error handler catches exceptions, export/import/reset functional</done>
  <resume-signal>Type "approved" or describe issues to fix</resume-signal>
</task>

</tasks>

<verification>
- TypeScript compiles: `npx tsc --noEmit`
- Linting passes: `npm run lint`
- All audio imports present in screens.ts, reward.ts, scene.ts, app.ts
- Human verifies complete flow
</verification>

<success_criteria>
App is visuell und auditiv angenehm, alle Phase 4 requirements met, bereit zum Testen mit dem Kind.
</success_criteria>

<output>
After completion, create `.planning/phases/04-polish-audio/04-04-SUMMARY.md`
</output>