Leaderboards Documentation

GAMEPLAY_GUIDE.md

@@ -148,6 +148,47 @@ Share puzzles with friends:
 
 ---
 
+## Leaderboards (Daily & Weekly)
+
+Wrdler features a robust leaderboard system to track top performances:
+
+- **Daily Leaderboards:** Top 20 scores for each day (UTC midnight reset)
+- **Weekly Leaderboards:** Top 20 scores for each ISO week (resets Monday UTC)
+- **Settings-Based:** Each unique combination of game-affecting settings (game mode, wordlist, free letters, etc.) has its own leaderboard. You compete only with players using the same settings.
+- **Qualification:** Only the top 20 scores (sorted by score, then time, then difficulty) are displayed for each leaderboard. You can still submit your score even if you don't qualify for the top 20.
+- **Automatic Submission:** After each game, you can submit your score to the leaderboards from the game over popup. Challenge submissions also submit to leaderboards.
+- **Leaderboard Page:** Access the Leaderboards from the sidebar to view daily, weekly, and historical results, filtered by your current settings.
+
+### How to View Leaderboards
+- Open the sidebar and click the "🏆 Leaderboards" button
+- Browse daily, weekly, and historical leaderboards
+- See your rank and compare with other players using the same settings
+
+---
+
+## Challenge Mode (Updated)
+
+Share puzzles with friends:
+1. Complete a game
+2. Click "Share Challenge" in the game-over popup
+3. Copy the short URL (e.g., `?game_id=abc123`)
+4. Friends can play the same wordlist and compare scores!
+
+**Challenge Leaderboard:**
+- Top 5 players for each challenge are displayed in the Challenge Mode banner
+- Sorted by: Highest score → Fastest time → Highest difficulty
+- Submit your result to join the challenge leaderboard and the daily/weekly leaderboards
+
+---
+
+## Leaderboard Submission & Ranking
+- After each game, enter your name (optional) and submit your score to the leaderboards
+- If your score qualifies for the top 20, your rank will be displayed
+- You can view your ranking for both daily and weekly leaderboards in the game over popup
+- All leaderboard data is stored securely in the cloud (Hugging Face repository)
+
+---
+
 ## Tips & Strategies
 
 ### Free Letter Selection
@@ -313,7 +354,7 @@ Once installed, Wrdler works offline with basic caching!
            │
       ┌────┴────┐
       │         │
-   ┌──▼──┐   ┌─▼──┐
+   ┌───▼──┐   ┌─▼──┐
    │ YES │   │ NO │
    └──┬──┘   └─┬──┘
       │        │

README.md

@@ -80,6 +80,14 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
 - **"Show Challenge Share Links" toggle** (default OFF) to control URL visibility
 - Each player gets different random words from the same wordlist
 
+### 🏆 Daily & Weekly Leaderboards (v0.2.0+)
+- **Daily Leaderboards:** Top 20 scores for each day (UTC midnight reset)
+- **Weekly Leaderboards:** Top 20 scores for each ISO week (resets Monday UTC)
+- **Settings-Based:** Each unique combination of game-affecting settings (game mode, wordlist, free letters, etc.) has its own leaderboard. You compete only with players using the same settings.
+- **Qualification:** Only the top 20 scores (sorted by score, then time, then difficulty) are displayed for each leaderboard. All submissions are stored, but only the best are shown.
+- **Automatic Submission:** After each game, you can submit your score to the leaderboards from the game over popup. Challenge submissions also submit to leaderboards.
+- **Leaderboard Page:** Access the Leaderboards from the sidebar to view daily, weekly, and historical results, filtered by your current settings.
+
 ### Deployment & Technical
 - **Dockerfile-based deployment** supported for Hugging Face Spaces and other container platforms
 - **Environment variables** for Challenge Mode (HF_API_TOKEN, HF_REPO_ID, SPACE_NAME)

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "wrdler"
 version = "0.2.0"
-description = "Wrdler vocabulary puzzle game - simplified version based on BattleWords with 8x6 grid, horizontal words only, no scope, and 2 free letter guesses. Features daily/weekly leaderboards."
+description = "Wrdler vocabulary puzzle game - simplified version based on BattleWords with 8x6 grid, horizontal words only, no scope, 2 free letter guesses, and a settings-based daily/weekly leaderboard system. Features leaderboard UI, challenge sharing, and AI word lists."
 readme = "README.md"
 requires-python = ">=3.12,<3.13"
 dependencies = [

specs/requirements.md

@@ -184,6 +184,30 @@ This document breaks down the implementation tasks for Wrdler using the game rul
 
 **Test Results:** ✅ 25/25 tests passing (100%)
 
+## Leaderboard System (v0.2.0+)
+
+- **Daily and Weekly Leaderboards:**
+  - Top 20 scores for each day (UTC midnight reset) and week (ISO week, resets Monday UTC)
+  - Each unique combination of game-affecting settings (game mode, wordlist, free letters, etc.) has its own leaderboard
+  - Scores are sorted by: score (descending), time (ascending), difficulty (descending)
+  - Only the top 20 scores are displayed per leaderboard, but all submissions are stored
+  - After each game, players can submit their score to the leaderboards from the game over popup
+  - Challenge submissions also submit to daily/weekly leaderboards
+  - Leaderboard navigation is available in the sidebar ("🏆 Leaderboards")
+  - Leaderboard page allows browsing daily, weekly, and historical leaderboards, filtered by current settings
+
+- **Challenge Mode (Updated):**
+  - Submitting a result to a challenge also submits to the appropriate daily/weekly leaderboards
+  - Challenge leaderboards remain for each challenge, but global leaderboards are now settings-based
+
+- **Data Privacy:**
+  - Only player name (optional), score, and game settings are stored in the leaderboard
+  - All leaderboard data is stored in the Hugging Face repository
+
+- **UI Integration:**
+  - Game over popup displays leaderboard submission status and rank if qualified
+  - Sidebar navigation for leaderboard page
+
 ## Sprint Completion Summary (v0.0.2)
 
 | Sprint | Description | Time | Tests | Status |

specs/specs.md

@@ -83,6 +83,15 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords, but with key
 - ✅ **Top 5 Display:** Leaderboard banner shows top 5 players
 - ✅ **Optional Sharing:** "Show Challenge Share Links" toggle (default OFF) controls URL visibility
 
+### Leaderboard System (v0.2.0+)
+Wrdler now features a daily and weekly leaderboard system:
+- **Daily Leaderboards:** Top 20 scores for each day (UTC midnight reset)
+- **Weekly Leaderboards:** Top 20 scores for each ISO week (resets Monday UTC)
+- **Settings-Based:** Each unique combination of game-affecting settings (game mode, wordlist, free letters, etc.) has its own leaderboard. You compete only with players using the same settings.
+- **Qualification:** Only the top 20 scores (sorted by score, then time, then difficulty) are displayed for each leaderboard. All submissions are stored, but only the best are shown.
+- **Automatic Submission:** After each game, you can submit your score to the leaderboards from the game over popup. Challenge submissions also submit to leaderboards.
+- **Leaderboard Page:** Access the Leaderboards from the sidebar to view daily, weekly, and historical results, filtered by your current settings.
+
 ### PWA Support
 - ✅ **PWA Installation:** App is installable as a Progressive Web App on desktop and mobile
   - Added `service worker` and `manifest.json`