# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

Touch-bedienbare Lern-PWA für Grundschulkinder (Schulanfänger, **kein Lesen vorausgesetzt**). Kinder üben Zahlzerlegungen für Zielzahlen 4–10 auf Zeit, thematisch als Raketenflug. Detaillierte Produktspezifikation in `BRAINSTORM.md` — bei UI-/UX-Entscheidungen dort zuerst nachsehen.

Kernprinzipien aus `BRAINSTORM.md`, die bei jeder Änderung beachtet werden müssen:
- **Kein Text** in der Spielfläche — nur Symbole, Zahlen, Animationen.
- **Keine Vermenschlichung** (keine Gesichter auf Rakete/Objekten).
- **Positives Feedback only** — keine Bestrafung bei falschen Antworten, kein Knall/Absturz.
- **Große Touchflächen** (mind. 84–96 px), `user-select: none`, `touch-action: manipulation`.
- **Sounds müssen abschaltbar** sein (global via Settings-Store).

## Commands

```bash
npm run dev      # Vite-Dev-Server auf :5173
npm run build    # Production-Build (Vite + vite-plugin-pwa)
npm run preview  # Build lokal servieren
npm run check    # svelte-check (Type-Check)
npm test         # Vitest einmal ausführen
npm run test:watch
npx vitest run path/to/foo.test.ts  # einzelne Test-Datei
```

Visuelle Verifikation mit `firefox-devtools`-MCP: Firefox via `swaymsg` floating + 1980×1200 stellen, dann `navigate_page` + `screenshot_page`. Beispiele für relevante Viewport-Größen: 1920×1080, 1280×720, 390×844.

## Architecture

### Tech-Stack
Svelte 5 (Runes-Mode: `$props()`, `$state()`, `$derived()`, `$effect()`) + Vite 6 + TypeScript (strict) + `vite-plugin-pwa`. Vitest mit jsdom-Environment. **Kein Backend** — alle Daten in `localStorage`.

### Drei-Schichten-Trennung in `src/lib/`

```
game/      — Pure Logic, framework-frei, Vitest-getestet
stores/    — Svelte-Stores; halten Reactive-State, syncen zu localStorage
components/, screens/, audio/  — UI; konsumieren Stores, lösen Aktionen aus
```

Diese Trennung ist load-bearing: **Logik nie in Komponenten**, **Storage-Zugriffe nur in `game/persistence.ts`**, **State-Mutations gehen über Store-Setter** (`startGame`, `answer`, `setRoundSeconds` …) statt direkter `.set()`-Aufrufe.

### State-Flow

`route` (writable) entscheidet, welcher Screen rendert (App.svelte switched per `if`). `game` ist der Spielzustand, wird per `startGame(target)` initialisiert und tickt selbst über `requestAnimationFrame` (`game.ts:tick`). Bei Antwort → `answer(value)` → ggf. `correctCount++`, neue Aufgabe via `generateTask`, `stageBumpKey` inkrementiert (FX-Trigger). Bei `correctCount === 10` oder Timer = 0 → `finalize()` schreibt in `progress`-Store, der via `subscribe`-Hook automatisch in `localStorage` persistiert.

`settings` und `progress` laden initial aus `localStorage` (mit Schema-Toleranz in `loadProgress`/`loadSettings`) und schreiben automatisch bei Änderungen zurück.

### Stufen-Mapping (Game-Design-Subtilität)

`stages.ts:stageFor(correct)` mappt 0..1→0 (Boden), 2..3→1 (Luftballon), 4..6→2 (Wolken), 7..9→3 (Mond), 10+→4 (Sterne). Stufe 5 (Regenbogenland) ist **kein** stageFor-Rückgabewert, sondern die Win-Celebration im ResultScreen. `BRAINSTORM.md` listet 5 Stufen aber nur 4 Schwellen (2/4/7/10) — Sterne und Regenbogenland sind im Endspiel zusammengefasst.

### Sound

`soundManager.ts` synthetisiert alle Sounds **generativ via WebAudio** (Oszillatoren + Noise-Bursts) — **keine Audio-Asset-Dateien** im Projekt. Mute global über `settings.soundOn`. Browser-Autoplay-Policy: `unlockAudio()` im ersten User-Tap aufrufen (HomeScreen, ResultScreen).

### PWA

`vite-plugin-pwa` mit `registerType: 'autoUpdate'` generiert Service Worker und Manifest. Icons in `public/icons/` werden per `rsvg-convert` aus `favicon.svg` gerendert (192/512). Bei Manifest-Änderungen muss SW neu generiert werden (`npm run build`).

### Test-Setup

`src/test-setup.ts` shimmt `localStorage`, weil **Node 25 ein kaputtes experimentelles `localStorage` mitbringt** (es überschreibt jsdoms Implementation, aber `clear` etc. fehlen). Der Setup-File ersetzt es vor jedem Test mit einer in-memory-Implementierung. Wenn neue jsdom-abhängige Globals nötig sind, dort hinzufügen.

## Styling-Konventionen

- Farben aus CSS-Variablen in `src/app.css` (`--c-*`). Nicht hartcodieren.
- Karten/Komponenten mit `aspect-ratio` brauchen Höhen-Constraints am Container, sonst Overflow auf breiten Schirmen — siehe `HomeScreen.svelte:.cards-grid` für die Formel `C·3·(H−(R−1)·g) / (4·R) + (C−1)·g`.
- `100dvh` statt `100vh` (mobile Browser-Chrome).

## Pitfalls

- **`isolatedModules: true`** in tsconfig: Type-Imports brauchen `import type`.
- **Svelte 5 Runes**: Nicht mit `let`-reactivity (alter Svelte 4-Stil) mischen. `$effect` kann Cleanup-Function returnieren.
- **`stageBumpKey`** als Trigger-Mechanismus: nur inkrementieren, wenn Stufe **wirklich** wechselt (nicht bei jeder richtigen Antwort) — siehe `game.ts:answer`.