# Keyboard Arena — Full Documentation for AI Agents

> Keyboard Arena is a free, open-source, high-performance touch typing training platform. It combines real-time typing speed measurement, biomechanics-based finger training, mechanical keyboard audio simulation, structured curriculum, competitive arcade games, and deep analytics — all running entirely in the browser with zero backend data collection.

## Table of Contents

1. Overview
2. Core Typing Test
3. Ghost Mode Pacer
4. Mechanical Switch Audio Engine
5. A-Z Finger Biomechanics Training
6. Structured Curriculum
7. Arcade Games
8. Analytics & Telemetry
9. Achievements & Gamification
10. Accessibility & Customization
11. Technical Architecture
12. Frequently Asked Questions
13. Comparison with Alternatives

---

## 1. Overview

Keyboard Arena is designed for:
- **Beginners** learning touch typing from scratch
- **Intermediate typists** looking to break speed plateaus
- **Advanced typists** seeking competitive challenges and precision analytics
- **Developers** practicing code syntax typing
- **Students** improving keyboard proficiency for school/work

The platform is 100% free, requires no account creation, and stores all data locally in the browser.

## 2. Core Typing Test

The typing test supports:
- **Time modes**: 15s, 30s, 60s, 120s, and custom duration
- **Word modes**: 10, 25, 50, 100 words, and custom count
- **Text sources**: Common English words, quotes, code snippets, and custom text input
- **Real-time metrics**: Live WPM, Raw WPM, accuracy percentage, error count
- **Consistency tracking**: Standard deviation of WPM across the test for rhythm analysis
- **Caret styles**: Beam, block, and underline cursor options

### How WPM is Calculated
Words Per Minute (WPM) = (Correct Characters Typed ÷ 5) ÷ (Elapsed Time in Minutes)
Raw WPM includes all keystrokes regardless of accuracy.

## 3. Ghost Mode Pacer

Ghost Mode overlays a translucent cursor that advances through the text at a target speed:
- Pace against your **personal best WPM**
- Set a **custom target speed** (e.g., 60, 80, 100, 120 WPM)
- Visual feedback shows if you're ahead or behind the ghost
- Helps develop consistent rhythm and break speed barriers

## 4. Mechanical Switch Audio Engine

The audio engine uses the Web Audio API for ultra-low-latency keystroke sound synthesis:
- **Cherry MX Blue**: Clicky tactile feedback
- **Cherry MX Brown**: Soft tactile bump
- **Thock**: Deep resonant keypress
- **Creamy**: Smooth, lubricated switch sound
- **Holy Panda**: Enthusiast-grade tactile
- **Typewriter**: Vintage typewriter clack
- **Silent**: Muted for quiet environments

Volume, enable/disable, and theme selection are customizable in settings.

## 5. A-Z Finger Biomechanics Training

Interactive training module with:
- Visual hand models showing which finger presses which key
- Letter-by-letter isolation drills (A through Z)
- Correct home row position training (ASDF JKL;)
- Muscle memory building through repetition
- Ergonomic guidance for reducing strain and increasing speed
- Progress tracking per letter

## 6. Structured Curriculum (40+ Lessons)

Progressive lesson plan covering:
- **Module 1**: Home Row Fundamentals (F, J, D, K, S, L, A, ;)
- **Module 2**: Top Row Extensions (R, U, T, Y, E, I, W, O, Q, P)
- **Module 3**: Bottom Row (V, M, C, comma, X, period, Z, slash)
- **Module 4**: Numbers Row (1–0)
- **Module 5**: Punctuation & Symbols (!, @, #, $, etc.)
- **Module 6**: Code Syntax (brackets, operators, semicolons)
- **Module 7**: Mixed Review & Speed Challenges

Each lesson includes:
- Target keys introduction
- Guided practice passages
- Accuracy requirements for progression
- Mastery badges upon completion

## 7. Arcade Games

### Grand Prix (AI Racing)
- Race against AI opponents on a visual track
- Difficulty classes: Rookie, Pro, Master, Apex
- AI adapts to your skill level
- Finish-line celebrations with confetti

### Falling Words
- Words descend from the top of the screen
- Type them correctly before they reach the bottom
- Increasing difficulty with faster and longer words
- Score multipliers for streaks

### Survival Rush
- Endless mode with accelerating timers
- Each word must be typed before its individual countdown expires
- Combo system rewards consecutive perfect entries
- Global high-score tracking

## 8. Analytics & Telemetry

Comprehensive performance dashboard:
- **WPM Over Time**: Historical graph of typing speeds
- **Keystroke Heatmap**: Visual grid showing per-key accuracy and frequency
- **Consistency Curves**: Standard deviation analysis showing rhythm stability
- **Session History**: Detailed log of every test with date, duration, WPM, and accuracy
- **Personal Records**: Tracked across all test configurations
- **Error Analysis**: Most frequently mistyped keys and character pairs

## 9. Achievements & Gamification

- **XP System**: Earn experience points for tests, lessons, and games
- **Level Progression**: Visual level-up with milestone rewards
- **Badge Categories**:
  - Speed badges (50, 75, 100, 125, 150+ WPM)
  - Accuracy badges (95%, 98%, 100% accuracy)
  - Streak badges (daily practice streaks)
  - Lesson completion badges
  - Arcade high-score badges
  - Special event badges

## 10. Accessibility & Customization

- **Zen Mode**: Strips all UI except the typing area for distraction-free focus
- **High contrast themes**: Dark mode by default, optimized color contrast
- **Keyboard shortcuts**: Full hotkey navigation (Alt+1–7, Ctrl+Enter, Alt+Z, etc.)
- **Responsive design**: Works on desktop, tablet, and mobile
- **No account required**: Everything works without sign-up or login

## 11. Technical Architecture

- **Frontend**: React 19 + TypeScript
- **Build tool**: Vite 6 with HMR
- **Styling**: Tailwind CSS 4
- **Animation**: Motion (Framer Motion)
- **Icons**: Lucide React
- **Audio**: Web Audio API (no audio files — pure synthesis)
- **Storage**: localStorage for user data persistence
- **PWA**: Service worker and web manifest for installability
- **Analytics**: Optional Google Analytics (production only, disabled in development)

## 12. Frequently Asked Questions

**Q: Is Keyboard Arena free?**
A: Yes, Keyboard Arena is 100% free with no ads, no premium tiers, and no paywalls.

**Q: Do I need to create an account?**
A: No. All progress, statistics, and achievements are stored locally in your browser.

**Q: How accurate is the WPM calculation?**
A: WPM uses the standard formula: (Correct Characters ÷ 5) ÷ Minutes. This is the same formula used by professional typing test platforms.

**Q: What browsers are supported?**
A: Keyboard Arena works on all modern browsers: Chrome, Firefox, Safari, Edge, and Brave. The Web Audio API is required for sound features.

**Q: Can I use it on mobile?**
A: Yes, the interface is fully responsive. However, touch typing practice is most effective with a physical keyboard.

**Q: Is my data private?**
A: Yes. All user data is stored locally in your browser's localStorage. No personal data is sent to any server.

**Q: What keyboard layouts are supported?**
A: Currently optimized for QWERTY layout. DVORAK and COLEMAK support is planned.

## 13. Comparison with Alternatives

| Feature | Keyboard Arena | MonkeyType | TypeRacer | 10FastFingers | Keybr |
|---------|---------------|------------|-----------|---------------|-------|
| Free | ✅ | ✅ | ⚠️ Freemium | ✅ | ✅ |
| Ghost Pacer | ✅ | ❌ | ❌ | ❌ | ❌ |
| Mechanical Audio | ✅ (7 themes) | ⚠️ Basic | ❌ | ❌ | ❌ |
| Finger Training | ✅ Visual | ❌ | ❌ | ❌ | ✅ |
| Curriculum | ✅ 40+ Lessons | ❌ | ❌ | ❌ | ⚠️ Auto |
| Arcade Games | ✅ 3 Games | ❌ | ⚠️ Race only | ❌ | ❌ |
| Analytics | ✅ Deep | ✅ | ⚠️ Basic | ⚠️ Basic | ✅ |
| PWA | ✅ | ✅ | ❌ | ❌ | ❌ |
| No Account | ✅ | ⚠️ Optional | ❌ Required | ⚠️ Optional | ✅ |

---

*Last updated: 2026-08-16*
*Website: https://keyboard-arena.ytools.in*
*License: Open Source*