Zauberwald/README.md

# Zauberwald

A magical typing tutor that teaches touch typing through an AI-generated enchanted forest.

Zauberwald is a web application that teaches a 7-year-old child touch typing using the QWERTZ keyboard layout. It combines structured typing exercises with a dynamically growing AI-generated forest world. Fixed lesson structure, surprising rewards — curiosity over performance pressure.

The child keeps practicing voluntarily because they want to see what appears next in the forest — not because of points or stars.

<!-- ![Screenshot](docs/screenshot.png) -->

## Features

- 10-finger touch typing with QWERTZ (DE/CH) on-screen keyboard with color-coded finger zones
- 3-phase micro-lessons: Discover, Practice, Build Words (90–120 seconds each)
- AI-generated forest rewards (Gemini API) — new forest elements appear after each completed lesson
- 4 companion characters (Fee Lila, Einhorn Stella, Fuchs Finn, Eule Elsa) with AI-generated dialogue
- Adaptive tempo that adjusts to the child's typing speed
- No visible scores, timers, or error counters — progress shown only through the growing forest
- Parent dashboard (Ctrl+Shift+E + access code) with statistics, export/import, and settings
- Audio feedback (key sounds, rewards) and optional speech output via Web Speech API
- Multi-forest pagination — as the forest fills up, new pages are created with arrow navigation between them
- Offline-capable with IndexedDB storage (images cached as blobs)
- Watercolor pastel art style with gentle animations

## Tech Stack

| Technology | Purpose |
|---|---|
| Vanilla TypeScript | Application logic (no framework) |
| Vite 6.x | Build tool and dev server |
| Biome | Linting and formatting |
| Vitest | Unit tests |
| Gemini API | Text generation (gemini-2.5-flash) and image generation (gemini-3.1-flash-image-preview) |
| IndexedDB | Client-side persistence (images stored as blobs) |
| Web Audio API | Key sounds and reward audio |
| Web Speech API | Optional voice output for companion dialogue |

## Prerequisites

- Node.js 18+
- npm
- A Google Gemini API key (for AI features; the app runs with built-in fallbacks without one)

## Getting Started

```bash
git clone https://codeberg.org/gurix/Zauberwald.git
cd Zauberwald
npm install
cp public/config.example.json public/config.json
# Edit public/config.json and add your Gemini API key
npm run dev
```

Then open http://localhost:5173

## Available Scripts

| Command | Description |
|---|---|
| `npm run dev` | Start dev server (listens on 0.0.0.0, port 5173) |
| `npm run build` | Type-check and build for production |
| `npm run preview` | Preview production build on port 4173 |
| `npm test` | Run tests once |
| `npm run lint` | Lint with Biome |
| `npm run lint:fix` | Lint and auto-fix with Biome |
| `npm run generate-assets` | Pre-generate companion character assets via Gemini API |

## Project Structure

```
src/
  api/          — Gemini API client and config loader
  audio/        — Sound effects and speech synthesis
  companion/    — Character definitions, AI dialogue, fallbacks
  forest/       — Forest scene rendering and reward logic
  game/         — Keyboard, levels, typing engine, word lists
  storage/      — IndexedDB persistence layer
  ui/           — Screen management and parent dashboard
  styles/       — CSS (single main.css with custom properties)
  assets/       — Companion avatars, character sheets, fallback SVGs
  types.ts      — Shared type definitions
  main.ts       — App entry point
  app.ts        — App initialization and routing
public/
  config.json   — Runtime config (API keys, not committed)
scripts/
  generate-assets.ts — Pre-generate character images
```

## How It Works

The child picks a companion character (a fairy, a unicorn, a fox, or an owl) and starts a level. There are 16 levels covering the entire keyboard — from the home row through the upper and lower rows to special characters. Lessons are designed to complete in under 5 minutes.

Each micro-lesson has three phases. In the Discover phase, new keys light up on the on-screen keyboard so the child sees which finger to use. In the Practice phase, single letters appear one at a time with adaptive timing — the interval adjusts based on the child's speed, always staying within comfortable bounds. In the Build Words phase, the child types short words using only the keys learned so far. Errors are invisible: a wrong key press does nothing, while the correct key pulses gently.

After completing a lesson, the forest grows. The app generates a new forest element image via the Gemini API (or uses SVG fallbacks when offline or when no API key is configured). The image is cached permanently in IndexedDB. Each forest page holds up to 12 elements — when it fills up, a new page is created. The child can navigate between forest pages using arrow buttons. The child is motivated to continue because they want to see what appears next in their forest — the reward is discovery, not a score.

## Configuration

Copy `public/config.example.json` to `public/config.json` and add your Gemini API key:

```json
{
  "geminiApiKey": "YOUR_API_KEY_HERE"
}
```

Notes:
- The app works without an API key using built-in fallback texts and SVG images.
- The API key is stored client-side. This is acceptable for private, single-user use.
- `public/config.json` is excluded from version control.

## Deployment

### Static Build

```bash
npm run build
# Serve the dist/ directory with any static file server
```

For a VPS preview of the production build:

```bash
npm run preview  # serves on 0.0.0.0:4173
```

### Docker

```bash
docker build -t zauberwald .
docker run -v /path/to/config.json:/app/dist/config.json:ro -p 4173:4173 zauberwald
```

Mount your `config.json` with the Gemini API key into the container. The app is then available at `http://localhost:4173`.

The dev server binds to `0.0.0.0` by default, making it accessible over the network without additional configuration. No HTTPS is required for local or private use.

## Contributing

Contributions are welcome. Please open an issue first to discuss what you would like to change.

## License

This project is not yet licensed. Please contact the author for usage terms.