Zauberwald/.planning/phases/01-grundger-st-tippmechanik/01-CONTEXT.md

Phase 1: Grundgerüst + Tippmechanik - Context

Gathered: 2026-03-29 (assumptions mode) Status: Ready for planning

## Phase Boundary

Eine spielbare Tipp-Übung im Browser, die ohne API funktioniert. Umfasst: Vite-Projekt-Setup, Projektstruktur, TypeScript-Interfaces, IndexedDB-Wrapper, Screen-Management, Willkommens-Screen mit Begleitfigur/Layout-Auswahl, QWERTZ-Bildschirmtastatur mit Fingerfarben, Übungsphase "Üben" (Buchstaben einzeln tippen), adaptives Tempo, Stufen 1–6 Daten, Stufenkarte, CSS-Palette/Typografie. Kein API-Zugriff, keine Bildgenerierung, keine Begleitfigur-Dialoge.

## Implementation Decisions

Screen Management Architecture

• D-01: All 5 screens (welcome, forest, lesson, reward, parent) exist as DOM containers in index.html, toggled via CSS classes with fade transitions. No dynamic DOM creation/destruction. Each screen is a <section> with a shared .screen class; only .screen--active is visible.

IndexedDB Schema

• D-02: Create the full IndexedDB schema with all 5 stores (progress, companionAssets, styleReference, forestElements, settings) in Phase 1. Only progress and settings get full read/write methods; other stores are structurally defined but unused until Phase 2+. This avoids painful version migrations later.

Typing Exercise Scope

• D-03: Phase 1 implements only the "Üben" (practice) phase — single letters appearing one at a time, typed by the child. "Entdecken" (TYPE-05) and "Wörter bauen" (TYPE-06) are Phase 3 scope. The lesson screen shows only the practice flow.
• D-04: A lesson consists of 8–12 random letters from the current level's key set. After all letters are correctly typed, the lesson is complete. No timer visible to the child.

Companion Placeholders

• D-05: Welcome screen uses emoji placeholders (🧚 🦄 🦊 🦉) with character names for companion selection. No companion figure appears during typing exercise. Real generated avatars replace these in Phase 2 (ASST-03).

Level Progression

• D-06: Levels 1–6 defined as static data with their key sets per the spec's progression table. A level counts as completed after one full playthrough (not perfection). Next level unlocks immediately.
• D-07: After completing a lesson, the app returns to the forest overview (Stufenkarte). No reward screen content in Phase 1 — the reward screen exists structurally but is skipped or shows a simple "Gut gemacht!" placeholder until Phase 3 adds Gemini-generated rewards.

Adaptive Tempo

• D-08: Start interval 3s. After 2 correct in sequence: -200ms (min 1.5s). After 1 error: +500ms (max 4s). Reset to 3s at start of each new lesson.

Claude's Discretion

• Screen transition timing and easing (CSS fade duration, easing function)
• Internal file/module organization within the spec's directory structure
• Exact DOM structure of keyboard component (divs vs buttons, row grouping)
• Test coverage scope — focus on typing logic and level progression, not DOM rendering

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

• SPEC.md — Full specification (sections 0–16), THE authoritative source for all design decisions
• SPEC.md section 4.1 — Level progression table (keys per level, finger assignments)
• SPEC.md section 6.2 — Tech stack decisions (all final)
• SPEC.md section 6.3 — IndexedDB store definitions
• SPEC.md section 7.2 — CSS color palette and typography
• SPEC.md section 8 — Keyboard layout, finger mapping, DE/CH differences
• SPEC.md section 13 — Project structure (directories + files)
• .planning/REQUIREMENTS.md — Phase 1 requirements: FNDN-01–05, ONBD-01–04, KYBD-01–05, TYPE-01–04, LEVL-01–03, FRST-04–05, PLSH-06
• public/config.json — Gemini API key and model names (not used in Phase 1 but structure exists) </canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

No existing code — greenfield project. The only assets are:

• public/config.json with Gemini API key and model names
• public/config.expample.json as template

Established Patterns

None yet — Phase 1 establishes all patterns. The spec mandates:

• Vanilla TypeScript, no framework
• Single main.css with CSS Custom Properties
• Biome for lint/format, Vitest for tests
• Vite 6.x with vanilla-ts template

Integration Points

• public/config.json — Phase 2 will read this for API access; Phase 1 should not depend on it
• IndexedDB stores — Phase 2+ will use companionAssets, styleReference, forestElements stores created here
• Screen management — Phase 3 will add dynamic content to forest and reward screens
• Keyboard component — Phase 3 "Entdecken" phase will highlight keys for new letter introduction </code_context>

## Specific Ideas

No specific requirements — open to standard approaches

## Deferred Ideas

None — analysis stayed within phase scope