feat: enhance statistics page UI with improved visual design

## Visual Improvements

### Mastery Breakdown
- Replace ⬤ with ■ symbol for consistency with heatmap legend
- Color icons to match mastery level (Green/Yellow/LightRed/Blue)
- Display actual keys under each mastery level (not truncated)
- Remove empty lines for tighter, cleaner spacing

### Weaknesses List
- Update title to "Weakest Keys (Lower = More Practice)"
- Change format from "1." to "#1" for emphasis
- Add "← WEAKEST" indicator for #1 entry (most practice needed)
- Ensure all top 10 keys are displayed

### Common Mistypes
- Increase from 5 to 10 items
- Display in 2-column layout for efficient space usage
- Remove empty lines for compact presentation

### Keyboard Heatmap Legend
- Update labels: "Good" → "Proficient", "Weak" → "Beginner"
- Change Beginner color from Red to Blue for better distinction from Learning (LightRed)

### Global Padding & Spacing
- Add horizontal and top padding to all blocks for breathing room
- Statistics blocks: Padding(1, 1, 1, 0) - left, right, top
- Menu lists: Padding(1, 1, 1, 0) for consistent spacing
- Lesson content blocks: Padding(2, 2, 1, 0) for enhanced readability
- Increase typing area height from 10 to 14 lines (7+7 with padding)
- Remove initial empty lines from all stat blocks for cleaner presentation

## Layout Adjustments

### Statistics Page
- Overall Performance: 8 lines
- Mastery Levels: 20 lines (displays all 4 levels with keys)
- Weakest Keys: 8 lines (compact, focused)
- Common Mistypes: 10+ lines (2-column layout)

### Lesson Screen
- Text blocks increased from Length(5) to Length(7) each
- Content area increased from 10 to 14 total lines
- Proper spacing between text and borders

## Technical Changes
- Update mastery breakdown to collect and display keys per level
- Implement 2-column layout for common mistypes using div_ceil
- Standardize padding across all UI components
- Maintain consistent color scheme throughout

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

Author: jrollin

CLAUDE.md

@@ -105,7 +105,7 @@ Located in `docs/steering/`:
   - Maintains category context after session completion
 
 **Phase 3.4 (Completed):**
-- **menu-grouping/** (`src/ui/render.rs`, `src/app.rs`) - Visual lesson grouping within categories ✅ NEW
+- **menu-grouping/** (`src/ui/render.rs`, `src/app.rs`) - Visual lesson grouping within categories
   - Category-aware lesson grouping with visual separators
   - **Languages category**: Grouped by language (French, English) with cyan separators
   - **Finger Training category**: Grouped by finger pair (Pinky, Ring, Middle, Index) with green separators
@@ -115,6 +115,17 @@ Located in `docs/steering/`:
   - Lesson ordering optimized for logical grouping
   - Improves navigation and lesson discovery within large categories
 
+**Phase 3.5 (Completed):**
+- **statistics-page/** (`src/ui/render.rs`, `src/app.rs`) - Comprehensive performance dashboard ✅ NEW
+  - Overall session statistics (sessions, keystrokes, WPM, accuracy)
+  - Mastery level breakdown (counts per classification: Mastered, Proficient, Learning, Beginner)
+  - Top 10 weaknesses list (< 80% accuracy with error details)
+  - Common mistype patterns (top 5 error patterns showing which keys are confused)
+  - Visual keyboard heatmap with accuracy-based color coding
+  - Accessible from main menu with 's' key
+  - Graceful placeholder when no analytics data exists
+  - Two-column layout optimized for terminal display (40% stats / 60% heatmap)
+
 **Complete documentation index**: See `docs/README.md` for navigation guide and feature details.
 
 ### User Documentation

README.md

@@ -57,14 +57,28 @@ Typer CLI is a terminal-based keyboard typing training tool. It provides an inte
 - ✅ **Smart ESC Navigation**: Lessons → Categories → Quit
 - ✅ **Context Preservation**: Returns to same category after completing session
 
-### Menu Grouping (Phase 3.4) ✅ NEW
+### Menu Grouping (Phase 3.4) ✅
 - ✅ **Visual Separators**: Lessons organized with colored dividers within categories
 - ✅ **Language Grouping**: Languages category groups French and English lessons separately
 - ✅ **Finger Grouping**: Finger Training groups by finger pair (Pinky, Ring, Middle, Index)
 - ✅ **Code Grouping**: Code category groups Code Patterns, TypeScript, Rust, and Python
 - ✅ **Color-Coded**: Separators match category colors for visual consistency
 - ✅ **Improved Navigation**: Easier to find and browse lessons within large categories
 
+### Statistics Dashboard (Phase 3.5) ✅
+- ✅ **Overall Metrics**: View total sessions, keystrokes, average WPM, and accuracy
+- ✅ **Visual Keyboard Heatmap**: See per-key accuracy with color-coded visualization
+  - Green: Mastered (90%+ accuracy)
+  - Yellow: Proficient (80-90% accuracy)
+  - Light Red: Learning (70-80% accuracy)
+  - Blue: Beginner (<70% accuracy)
+  - Heatmap always shown (optimized for analytics view)
+- ✅ **Mastery Breakdown**: Colored icons (■) showing keys in each mastery level
+- ✅ **Weakness Identification**: Top 10 weakest keys with error counts (#1 = most practice needed)
+- ✅ **Error Patterns**: Top 10 common mistypes in 2-column layout
+- ✅ **Polished UI**: Enhanced padding and spacing for better readability
+- ✅ **Access**: Press `s` key from the main menu (after completing your first session)
+
 **Total Lessons**: 77 (52 standard + 24 finger training + 1 adaptive)
 
 ## Installation

docs/README.md

@@ -184,9 +184,23 @@ Hierarchical navigation system for improved lesson discovery.
 - ESC navigation: Lessons → Categories → Quit
 - Context preservation after session completion
 
+#### [statistics-page/](features/statistics-page/) ✅ COMPLETED
+Performance analytics dashboard with visual keyboard heatmap.
+
+**Module**: `src/ui/render.rs`, `src/app.rs`
+
+- Overall session statistics (sessions, keystrokes, WPM, accuracy)
+- Mastery level breakdown (Mastered, Proficient, Learning, Beginner counts)
+- Top 10 weaknesses list (< 80% accuracy with error details)
+- Common mistype patterns (top 5 error patterns)
+- Visual keyboard heatmap with accuracy-based color coding
+- Two-column layout (40% stats / 60% heatmap)
+- Accessible via 's' key from main menu
+- Graceful placeholder when no analytics data exists
+
 ### Future Features (Phase 3+)
 
-- **Analytics visualization** - Heat maps, trend graphs, progress charts
+- **Enhanced analytics** - Trend graphs, progress charts over time, session history visualization
 - **Enhanced adaptive UI** - Pre/post-session feedback, progress indicators
 - **Data export** - JSON/CSV export for external analysis
 - **Themes** - Multiple color schemes, high contrast options
@@ -257,16 +271,16 @@ Module locations are documented in each feature's design.md:
 
 ## Project Status
 
-**Current Phase**: Phase 3.3 Complete (Two-Level Menu System) ✓
+**Current Phase**: Phase 3.5 Complete (Statistics Dashboard) ✓
 
 **Total Tests**: 129 passing
 - 13 tests: typing-session
 - 7 tests: home-row-lessons
 - 12 tests: bigram-training
 - 12 tests: code-symbols
-- 9 tests: analytics (NEW)
-- 9 tests: adaptive algorithms (NEW)
-- 6 tests: adaptive generator (NEW)
+- 9 tests: analytics
+- 9 tests: adaptive algorithms
+- 6 tests: adaptive generator
 - 7 tests: session-storage
 - 2 tests: keyboard-layout
 - 3 tests: content generation
@@ -284,10 +298,12 @@ Module locations are documented in each feature's design.md:
 - Phase 3.1: Layout improvements ✓
 - Phase 3.2: Finger training ✓
 - Phase 3.3: Two-level menu system ✓
+- Phase 3.4: Menu grouping ✓
+- Phase 3.5: Statistics dashboard ✓
 
 **Total Lessons**: 77 (52 standard + 24 finger training + 1 adaptive)
 
-**Next Phase**: Analytics visualization and data export (Phase 3+)
+**Next Phase**: Enhanced analytics (trend graphs, data export) and gamification (Phase 3+)
 
 ## Additional Resources
 

docs/features/statistics-page/design.md

@@ -0,0 +1,70 @@
+# Statistics Page - Design
+
+## Architecture
+
+### State Machine
+- Add `Statistics` variant to `AppState` enum
+- Navigation: LessonTypeMenu ↔ Statistics
+- Render statistics via `ui::render_statistics()`
+
+### Layout Structure
+Two-column layout (40% / 60%):
+- Left: Overall stats, Mastery breakdown, Weaknesses, Mistypes
+- Right: Keyboard heatmap visualization
+
+### Data Flow
+```
+Stats (loaded from disk)
+  ├─→ adaptive_analytics: Option<AdaptiveAnalytics>
+      ├─→ key_stats: HashMap<char, KeyStats>
+      ├─→ total_sessions, total_keystrokes
+      └─→ session_history
+  └─→ sessions: Vec<SessionRecord>
+```
+
+### Component Breakdown
+1. `render_statistics()` - Main orchestrator
+2. `render_overall_stats_block()` - Session summary
+3. `render_mastery_breakdown()` - Key classification counts
+4. `render_weaknesses_list()` - Top 10 weak keys
+5. `render_common_mistypes()` - Error pattern analysis
+6. `render_keyboard_with_heatmap()` - Keyboard visualization with heatmap always enabled
+
+### Statistics-Specific Behavior
+- Heatmap is **always enabled** in statistics context (cannot be toggled off)
+- Finger color hints are **disabled** (heatmap takes priority)
+- Footer keyboard shortcuts are **hidden** (not needed, we have our own instructions)
+- This creates a cleaner, more focused analytics view
+
+### Color Scheme
+- Headers: Cyan + Bold
+- Metric values: Yellow
+- Mastery levels: Green/Yellow/LightRed/Red
+- Instructions: Gray
+
+### Edge Cases
+- No analytics data → Show placeholder
+- No weak keys → Congratulatory message
+- No mistypes → Perfect accuracy message
+- Terminal < 25 lines → Compact layout
+
+## Technical Decisions
+
+### Why Two-Column Layout?
+- Efficient use of horizontal space
+- All info visible at once (no scrolling)
+- Keyboard is central visual feature
+
+### Why Show 's' Option Always?
+- Simplifies menu logic
+- Statistics page handles no-data case internally
+- Encourages users to complete sessions
+
+### Why Filter < 5 Attempts?
+- Prevents noise from newly introduced keys
+- Ensures statistically meaningful weakness identification
+
+## Dependencies
+- Existing: `src/ui/keyboard.rs` (render_keyboard)
+- Existing: `src/data/stats.rs` (all analytics methods)
+- Existing: `src/engine/analytics.rs` (KeyStats, MasteryLevel)

docs/features/statistics-page/requirements.md

@@ -0,0 +1,61 @@
+# Statistics Page - Requirements
+
+## Purpose
+Provide users with comprehensive performance analytics to track progress and identify areas for improvement.
+
+## User Stories
+
+### US-1: Access Statistics
+WHEN a user presses 's' from the category menu
+THE SYSTEM SHALL display the statistics visualization page
+
+### US-2: View Overall Performance
+WHEN a user views the statistics page
+THE SYSTEM SHALL display overall session metrics including:
+- Total sessions completed
+- Total keystrokes typed
+- Average WPM across all sessions
+- Average accuracy across all sessions
+
+### US-3: View Mastery Breakdown
+WHEN a user views the statistics page
+THE SYSTEM SHALL display a count of keys in each mastery level:
+- Mastered (>95% accuracy)
+- Proficient (85-95% accuracy)
+- Learning (70-85% accuracy)
+- Beginner (<70% accuracy)
+
+### US-4: Identify Weaknesses
+WHEN a user views the statistics page
+THE SYSTEM SHALL display the top 10 keys with accuracy below 80%
+AND sort them by accuracy (lowest first)
+AND exclude keys with fewer than 5 attempts
+
+### US-5: View Common Errors
+WHEN a user views the statistics page
+THE SYSTEM SHALL display the top 5 most common mistype patterns
+AND show which key was expected and which was typed instead
+
+### US-6: Visual Keyboard Heatmap
+WHEN a user views the statistics page
+THE SYSTEM SHALL display a visual AZERTY keyboard with heatmap coloring
+AND color each key based on its accuracy:
+- Green: 90%+ (Mastered)
+- Yellow: 80-90% (Good)
+- LightRed: 70-80% (Learning)
+- Red: <70% (Weak)
+
+### US-7: No Data Handling
+WHEN a user accesses statistics with no session data
+THE SYSTEM SHALL display a placeholder message encouraging first session completion
+
+### US-8: Navigation
+WHEN a user presses ESC or 'q' on the statistics page
+THE SYSTEM SHALL return to the category menu
+
+## Acceptance Criteria
+- Statistics accessible via 's' key from main menu
+- Layout responsive to terminal size (minimum 80x24)
+- Colors consistent with application theme
+- All metrics calculated accurately from stored analytics
+- Placeholder shown gracefully when no data exists

docs/features/statistics-page/tasks.md

@@ -0,0 +1,42 @@
+# Statistics Page - Implementation Tasks
+
+## Phase 1: Core Implementation
+
+### State Machine Changes (src/app.rs)
+- [x] Add `Statistics` variant to AppState enum (line 24)
+- [x] Add render call in main loop (~line 295)
+- [x] Add 's' key handler in LessonTypeMenu state (~line 375)
+- [x] Add ESC/q handler for Statistics state (~line 510)
+
+### UI Rendering (src/ui/render.rs)
+- [x] Create `render_statistics()` main function (~line 923)
+- [x] Implement 3-section layout (Header | Content | Instructions)
+- [x] Implement 2-column content split (40% / 60%)
+- [x] Create `render_overall_stats_block()` helper
+- [x] Create `render_mastery_breakdown()` helper
+- [x] Create `render_weaknesses_list()` helper
+- [x] Create `render_common_mistypes()` helper
+- [x] Integrate keyboard heatmap rendering
+- [x] Add placeholder for no data scenario
+- [x] Update category menu instructions (line 843)
+
+## Phase 2: Testing
+- [x] Test with no data (fresh install)
+- [x] Test with analytics data (10+ sessions)
+- [x] Test perfect performance (no weaknesses)
+- [x] Test navigation flow (menu → stats → menu)
+- [x] Test terminal resize (80x24, 100x30, 120x40)
+- [x] Verify color accuracy matches mastery levels
+- [x] Cross-check displayed stats with JSON file
+
+## Phase 3: Documentation
+- [x] Update CLAUDE.md with Phase 3.5 section
+- [x] Update README.md with Statistics Dashboard feature
+- [x] Create feature documentation (requirements.md, design.md, tasks.md)
+- [x] Update docs/README.md index if needed
+
+## Phase 4: Polish
+- [x] Verify consistent color scheme
+- [x] Test edge cases (no weaknesses, no mistypes)
+- [x] Ensure proper error handling
+- [x] Code review for consistency with app patterns

src/app.rs

@@ -17,6 +17,7 @@ use crate::ui::keyboard::KeyboardConfig;
 #[derive(Debug, PartialEq)]
 enum AppState {
     LessonTypeMenu,
+    Statistics,
     LessonMenu,
     DurationMenu,
     Running,
@@ -241,6 +242,14 @@ impl App {
                 AppState::LessonTypeMenu => {
                     ui::render_lesson_type_menu(f, &self.categories, self.selected_category);
                 }
+                AppState::Statistics => {
+                    ui::render_statistics(
+                        f,
+                        &self.stats,
+                        &self.keyboard_layout,
+                        &self.keyboard_config,
+                    );
+                }
                 AppState::LessonMenu => {
                     let filtered_lessons: Vec<_> =
                         self.filtered_lessons().into_iter().cloned().collect();
@@ -343,6 +352,9 @@ impl App {
                 KeyCode::Esc | KeyCode::Char('q') => {
                     self.state = AppState::Quit;
                 }
+                KeyCode::Char('s') | KeyCode::Char('S') => {
+                    self.state = AppState::Statistics;
+                }
                 KeyCode::Up | KeyCode::Char('k') => {
                     if self.selected_category > 0 {
                         self.selected_category -= 1;
@@ -504,6 +516,12 @@ impl App {
                     _ => {}
                 }
             }
+            AppState::Statistics => match key.code {
+                KeyCode::Esc | KeyCode::Char('q') => {
+                    self.state = AppState::LessonTypeMenu;
+                }
+                _ => {}
+            },
             AppState::Quit => {}
         }
 

src/engine/analytics.rs

@@ -9,7 +9,7 @@ use super::types::CharInput;
 use super::types::TypingSession;
 
 /// Mastery level classification for keys and bigrams
-#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub enum MasteryLevel {
     Beginner,   // < 70% accuracy or < 5 attempts
     Learning,   // 70-85% accuracy