---
phase: quick
plan: 260329-uos
subsystem: game/levels
tags: [levels, words, keyboard, fallbacks, qwertz]
key_files:
  modified:
    - src/game/levels.ts
    - src/game/words.ts
    - src/game/keyboard.ts
    - src/companion/fallbacks.ts
    - src/game/levels.test.ts
    - src/game/words.test.ts
    - src/companion/companion.test.ts
decisions:
  - "Level 16 uses words-with-period (e.g. 'gut.') for punctuation practice since period doesn't appear in regular German words"
  - "companion.test.ts unknown-letter test updated to use '@' since all regular keys now have fallback entries"
metrics:
  duration: 4min
  completed: "2026-03-29"
  tasks: 3
  files: 7
---

# Quick Task 260329-uos: Level-Erweiterung für gesamten Tastaturbereich - Summary

**One-liner:** 16 QWERTZ levels added with German word lists (levels 7-16) covering r,u,t,z,w,o,q,p,n,b,v,m,c,x,ä,ü,y, comma, and period.

## What Was Done

Extended the typing game from 6 to 16 levels so children can learn all keys on the QWERTZ keyboard step by step.

### Task 1: Level-Definitionen und fingerMap erweitern

- Added levels 7-16 to `src/game/levels.ts` with proper `newKeys`, `allKeys`, and shared `fingerMap`
- Added `,` (`--finger-r-mid`) and `.` (`--finger-r-ring`) to the fingerMap
- Updated `src/game/keyboard.ts` bottom row: `["y","x","c","v","b","n","m",",","."]` in both DE and CH layouts
- Added `,` and `.` to `fingerColorMap` in keyboard.ts

**Commit:** 374298b

### Task 2: Wortlisten und Fallback-Texte für neue Level

- Added 10 validated German words per level for levels 7-16 in `src/game/words.ts`
- All words verified to use only keys known up to that level (max 5 characters)
- Level 16 uses short words with trailing period (e.g., "gut.", "hier.") for punctuation practice
- Added 19 new `LetterIntro` entries to `src/companion/fallbacks.ts` for: r,u,t,z,w,o,q,p,n,b,v,m,c,x,ä,ü,y,",","."
- Updated entry count comment to "32 entries, levels 1-16"

**Commit:** 1d4c709

### Task 3: Tests aktualisieren für 16 Level

- `levels.test.ts`: Updated length assertion from 6 to 16; added `newKeys` tests for levels 7-16; added Level 16 allKeys completeness test
- `words.test.ts`: Extended all loops from `<= 6` to `<= 16`; changed description to "levels 1-16"; added explicit `validateWordList()` test
- `companion.test.ts` (deviation): Fixed "unknown letter" test — was using 'z' which now has a fallback entry; updated to use '@' (truly unknown character)

**Commit:** 3a71799

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] companion.test.ts "unknown letter" test broken by new fallback entries**
- **Found during:** Task 3 (full test suite run)
- **Issue:** The test used letter 'z' to test the "no fallback found" code path. After Task 2 added 'z' to `fallbackLetterIntros` (Level 8), the test received a real text instead of the default message.
- **Fix:** Changed test letter from 'z' to '@' (a non-letter character that will never have a fallback entry)
- **Files modified:** src/companion/companion.test.ts
- **Commit:** 3a71799

## Key Decisions

1. **Level 16 word format:** Period doesn't appear naturally in German words, so level 16 uses "word." format (e.g., "gut.", "hier.") to practice the period key while keeping the max-5-char constraint.
2. **Unknown letter test:** Using '@' as the canonical "truly unknown" letter in tests, since all keyboard characters (a-z, umlauts, punctuation) now have fallback entries.

## Known Stubs

None — all levels are fully wired with word lists and fallback texts.

## Self-Check: PASSED

- src/game/levels.ts — FOUND, contains `level: 16`
- src/game/words.ts — FOUND, contains `wordsByLevel` entries for levels 7-16
- src/game/keyboard.ts — FOUND, bottom row includes "," and "."
- src/companion/fallbacks.ts — FOUND, contains 32 letter intro entries
- All 104 tests pass (8 test files)
- Commits: 374298b, 1d4c709, 3a71799
