From 4d95cb68cc7da654f37d3b2987a853b863125bd9 Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Sun, 29 Mar 2026 21:50:53 +0200 Subject: [PATCH] docs(260329-ua1): create English open-source README.md - Full project overview with tagline and concept description - Features, tech stack, prerequisites, getting started sections - Available scripts table, project structure tree - How It Works explanation of the three-phase lesson loop - Configuration, deployment, contributing, and license sections --- README.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..6302f2b --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +# 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 + +```bash +git clone +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: + +```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 + +```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 +``` + +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.