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.

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

git clone <repo-url>
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. Each level introduces new keys on the home row, with levels 1–6 available in the current version. 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. 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:

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

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

For a VPS preview of the production build:

npm run preview  # serves on 0.0.0.0: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.