Leaderboards Part 1

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "wrdler"
-version = "0.1.0"
-description = "Wrdler vocabulary puzzle game - simplified version based on BattleWords with 8x6 grid, horizontal words only, no scope, and 2 free letter guesses"
+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."
 readme = "README.md"
 requires-python = ">=3.12,<3.13"
 dependencies = [

specs/leaderboard_spec.md

@@ -0,0 +1,1431 @@
+# Wrdler Leaderboard System Specification
+
+**Document Version:** 1.2.0  
+**Target Project Version:** 0.2.0  
+**Author:** GitHub Copilot  
+**Date:** 2025-01-27  
+**Status:** Draft
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#1-executive-summary)
+2. [Goals and Objectives](#2-goals-and-objectives)
+3. [System Architecture](#3-system-architecture)
+4. [Data Models](#4-data-models)
+5. [New Python Modules](#5-new-python-modules)
+6. [Implementation Steps](#6-implementation-steps)
+7. [Version Changes](#7-version-changes)
+8. [File Changes Summary](#8-file-changes-summary)
+9. [API Reference](#9-api-reference)
+10. [UI Components](#10-ui-components)
+11. [Testing Requirements](#11-testing-requirements)
+12. [Migration Notes](#12-migration-notes)
+
+---
+
+## 1. Executive Summary
+
+This specification describes the implementation of a **Daily and Weekly Leaderboard System** for Wrdler. The system will:
+
+- Track top 20 scores for daily leaderboards (reset at UTC midnight)
+- Track top 20 scores for weekly leaderboards (reset at UTC Monday 00:00)
+- **Create separate leaderboards for each unique combination of game-affecting settings**
+- Automatically add qualifying scores from any game completion (including challenge mode)
+- Provide a dedicated leaderboard page with historical lookup capabilities
+- Store leaderboard data in HuggingFace repository using existing storage infrastructure
+- **Use a unified JSON format consistent with existing challenge settings.json files**
+
+---
+
+## 2. Goals and Objectives
+
+### Primary Goals
+
+1. **Settings-Based Leaderboards**: Each unique combination of game-affecting settings creates a separate leaderboard. Players using different settings compete on different leaderboards.
+
+2. **Daily Leaderboards**: Create and maintain daily leaderboards with top 20 entries displayed (can store more), organized by date folders (e.g., `leaderboards/daily/2025-01-27/`)
+
+3. **Weekly Leaderboards**: Create and maintain weekly leaderboards with top 20 entries displayed (can store more), organized by ISO week folders (e.g., `leaderboards/weekly/2025-W04/`)
+
+4. **Automatic Qualification**: Every game completion (challenge or solo) checks if score qualifies for the matching daily/weekly leaderboard based on current settings
+
+5. **Leaderboard Page**: New Streamlit page displaying:
+   - Last 7 days of daily leaderboards (filtered by current settings)
+   - Current weekly leaderboard (filtered by current settings)
+   - Historical lookup via dropdown
+
+6. **Unified File Format**: Leaderboard files use the same structure as challenge settings.json with an `entry_type` field to distinguish between "daily", "weekly", and "challenge" entries
+
+### Secondary Goals
+
+- Maintain backward compatibility with existing challenge system
+- Minimize HuggingFace API calls through caching
+- Support sorting by score (descending), then time (ascending), then difficulty (descending)
+- Use `challenge_id` as the primary identifier across all entry types
+
+### Game-Affecting Settings
+
+The following settings define a unique leaderboard:
+
+| Setting | Type | Description |
+|---------|------|-------------|
+| `game_mode` | string | `"classic"`, `"easy"`, `"too easy"` |
+| `wordlist_source` | string | Wordlist file (e.g., `"classic.txt"`, `"easy.txt"`) |
+| `show_incorrect_guesses` | bool | Whether incorrect guesses are shown |
+| `enable_free_letters` | bool | Whether free letters feature is enabled |
+| `puzzle_options` | object | Puzzle configuration (`spacer`, `may_overlap`) |
+
+**Example:** A player using `game_mode: "easy"` with `wordlist_source: "easy.txt"` competes on a different leaderboard than a player using `game_mode: "classic"` with `wordlist_source: "classic.txt"`.
+
+---
+
+## 3. System Architecture
+
+### 3.1 Storage Structure
+
+Each date/week can have multiple leaderboard folders, one per unique settings combination. The folder name includes the file_id suffix, and all leaderboards use `settings.json` as the filename (consistent with challenges):
+
+```
+HF_REPO_ID/
+??? games/                          # Existing challenge storage
+?   ??? {challenge_id}/
+?       ??? settings.json           # entry_type: "challenge"
+??? leaderboards/
+?   ??? daily/
+?   ?   ??? 2025-01-27-0/           # First settings combination for 2025-01-27
+?   ?   ?   ??? settings.json
+?   ?   ??? 2025-01-27-1/           # Second settings combination for 2025-01-27
+?   ?   ?   ??? settings.json
+?   ?   ??? 2025-01-26-0/
+?   ?       ??? settings.json
+?   ??? weekly/
+?   ?   ??? 2025-W04-0/             # First settings combination for week 4
+?   ?   ?   ??? settings.json
+?   ?   ??? 2025-W04-1/
+?   ?   ?   ??? settings.json
+?   ?   ??? 2025-W03-0/
+?   ?       ??? settings.json
+?   ??? index.json                  # Index of all leaderboards (maps settings to folder IDs)
+??? shortener.json                  # Existing URL shortener
+```
+
+### 3.2 Leaderboard Index File
+
+The `index.json` file maps settings combinations to folder identifiers for fast lookup:
+
+```json
+{
+  "daily": {
+    "2025-01-27": [
+      {
+        "file_id": 0,
+        "game_mode": "classic",
+        "wordlist_source": "classic.txt",
+        "show_incorrect_guesses": true,
+        "enable_free_letters": true,
+        "puzzle_options": {"spacer": 0, "may_overlap": false}
+      },
+      {
+        "file_id": 1,
+        "game_mode": "easy",
+        "wordlist_source": "easy.txt",
+        "show_incorrect_guesses": true,
+        "enable_free_letters": true,
+        "puzzle_options": {"spacer": 0, "may_overlap": false}
+      }
+    ]
+  },
+  "weekly": {
+    "2025-W04": [
+      {
+        "file_id": 0,
+        "game_mode": "classic",
+        "wordlist_source": "classic.txt",
+        "show_incorrect_guesses": true,
+        "enable_free_letters": true,
+        "puzzle_options": {"spacer": 0, "may_overlap": false}
+      }
+    ]
+  }
+}
+```
+
+### 3.3 Data Flow
+
+```
+??????????????????????
+?  Game Completion   ?
+??????????????????????
+          ?
+          ?
+??????????????????????
+? Get current game   ?
+? settings           ?
+??????????????????????
+          ?
+          ?
+??????????????????????
+? Find matching      ?
+? leaderboard or     ?
+? create new one     ?
+??????????????????????
+          ?
+    ?????????????
+    ?           ?
+    ?           ?
+????????? ???????????
+? Daily ? ? Weekly  ?
+? LB    ? ? LB      ?
+????????? ???????????
+    ?          ?
+    ????????????
+         ?
+         ?
+?????????????????????
+? Check if score    ?
+? qualifies (top    ?
+? 20 displayed)     ?
+?????????????????????
+          ?
+          ?
+?????????????????????
+? Update & Upload   ?
+? to HF repo        ?
+?????????????????????
+```
+
+---
+
+## 4. Data Models
+
+### 4.1 Entry Type Definition
+
+The `entry_type` field distinguishes between different types of game entries:
+
+| entry_type | Description | Storage Location |
+|------------|-------------|------------------|
+| `"challenge"` | Player-created challenge for others to compete | `games/{challenge_id}/settings.json` |
+| `"daily"` | Daily leaderboard entry | `leaderboards/daily/{date}-{file_id}/settings.json` |
+| `"weekly"` | Weekly leaderboard entry | `leaderboards/weekly/{week}-{file_id}/settings.json` |
+
+### 4.2 Unified File Schema (Consistent with Challenge settings.json)
+
+Both leaderboard files and challenge files use the **same base structure**. The settings in the file define what makes this leaderboard unique:
+
+```json
+{
+  "challenge_id": "2025-01-27-0",
+  "entry_type": "daily",
+  "game_mode": "classic",
+  "grid_size": 8,
+  "puzzle_options": {
+    "spacer": 0,
+    "may_overlap": false
+  },
+  "users": [
+    {
+      "uid": "20251130T190249Z-0XLG5O",
+      "username": "Charles",
+      "word_list": ["CHEER", "PLENTY", "REAL", "ARRIVE", "DEAF", "DAILY"],
+      "word_list_difficulty": 117.48,
+      "score": 39,
+      "time": 132,
+      "timestamp": "2025-11-30T19:02:49.544933+00:00",
+      "source_challenge_id": null
+    }
+  ],
+  "created_at": "2025-11-30T19:02:49.544933+00:00",
+  "version": "0.2.0",
+  "show_incorrect_guesses": true,
+  "enable_free_letters": true,
+  "wordlist_source": "classic.txt",
+  "game_title": "Wrdler Gradio AI",
+  "max_display_entries": 20
+}
+```
+
+### 4.3 Field Descriptions
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `challenge_id` | string | Unique identifier. For daily: `"2025-01-27-0"`, weekly: `"2025-W04-0"`, challenge: `"20251130T190249Z-ABCDEF"` |
+| `entry_type` | string | One of: `"daily"`, `"weekly"`, `"challenge"` |
+| `game_mode` | string | Game difficulty: `"classic"`, `"easy"`, `"too easy"` |
+| `grid_size` | int | Grid width (8 for Wrdler) |
+| `puzzle_options` | object | Puzzle configuration (defines leaderboard uniqueness) |
+| `users` | array | Array of user entries (sorted by score desc, time asc, difficulty desc) |
+| `created_at` | string | ISO 8601 timestamp when entry was created |
+| `version` | string | Schema version |
+| `show_incorrect_guesses` | bool | Display setting (defines leaderboard uniqueness) |
+| `enable_free_letters` | bool | Free letters feature toggle (defines leaderboard uniqueness) |
+| `wordlist_source` | string | Source wordlist file (defines leaderboard uniqueness) |
+| `game_title` | string | Game title for display |
+| `max_display_entries` | int | Maximum entries to display (default 20, can store more) |
+
+### 4.4 User Entry Schema
+
+Each user entry in the `users` array:
+
+```json
+{
+  "uid": "20251130T190249Z-0XLG5O",
+  "username": "Charles",
+  "word_list": ["CHEER", "PLENTY", "REAL", "ARRIVE", "DEAF", "DAILY"],
+  "word_list_difficulty": 117.48,
+  "score": 39,
+  "time": 132,
+  "timestamp": "2025-11-30T19:02:49.544933+00:00",
+  "source_challenge_id": null
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `uid` | string | Unique user entry ID |
+| `username` | string | Player display name |
+| `word_list` | array | 6 words played |
+| `word_list_difficulty` | float | Calculated difficulty score |
+| `score` | int | Final score |
+| `time` | int | Time in seconds |
+| `timestamp` | string | ISO 8601 when entry was recorded |
+| `source_challenge_id` | string\|null | If from a challenge, the original challenge_id |
+
+### 4.5 Settings Matching
+
+Two leaderboards are considered the same if ALL of the following match:
+- `game_mode`
+- `wordlist_source`
+- `show_incorrect_guesses`
+- `enable_free_letters`
+- `puzzle_options.spacer`
+- `puzzle_options.may_overlap`
+
+### 4.6 Weekly Leaderboard Naming
+
+Uses ISO 8601 week numbering:
+- Format: `YYYY-Www` (e.g., `2025-W04`)
+- Week starts on Monday
+- Week 1 is the week containing the first Thursday of the year
+
+---
+
+## 5. New Python Modules
+
+### 5.1 `wrdler/leaderboard.py` (NEW FILE)
+
+**Purpose:** Core leaderboard logic for managing daily and weekly leaderboards with settings-based separation.
+
+```python
+# wrdler/leaderboard.py
+"""
+Wrdler Leaderboard System
+
+Manages daily and weekly leaderboards with automatic score submission,
+qualification checking, and historical lookup.
+
+Leaderboard Configuration:
+- Max display entries: 20 per leaderboard (can store more)
+- Daily reset: UTC midnight
+- Weekly reset: Monday UTC 00:00 (ISO week)
+- Sorting: score (desc), time (asc), difficulty (desc)
+- File format: Unified with challenge settings.json
+- Settings-based separation: Each unique settings combination gets its own leaderboard
+"""
+__version__ = "0.2.0"
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone, timedelta
+from typing import Dict, Any, List, Optional, Tuple, Literal
+import logging
+
+from wrdler.modules.storage import (
+    _get_json_from_repo,
+    _upload_json_to_repo
+)
+from wrdler.modules.constants import HF_REPO_ID, APP_SETTINGS
+from wrdler.game_storage import generate_uid
+
+logger = logging.getLogger(__name__)
+
+# Configuration
+MAX_DISPLAY_ENTRIES = 20
+DAILY_LEADERBOARD_PATH = "leaderboards/daily"
+WEEKLY_LEADERBOARD_PATH = "leaderboards/weekly"
+LEADERBOARD_INDEX_PATH = "leaderboards/index.json"
+
+# Entry types
+EntryType = Literal["daily", "weekly", "challenge"]
+
+
+@dataclass
+class GameSettings:
+    """Settings that define a unique leaderboard."""
+    game_mode: str = "classic"
+    wordlist_source: str = "classic.txt"
+    show_incorrect_guesses: bool = True
+    enable_free_letters: bool = True
+    puzzle_options: Dict[str, Any] = field(default_factory=lambda: {"spacer": 0, "may_overlap": False})
+
+    def matches(self, other: "GameSettings") -> bool:
+        """Check if two settings are equivalent (same leaderboard)."""
+        return (
+            self.game_mode == other.game_mode and
+            self.wordlist_source == other.wordlist_source and
+            self.show_incorrect_guesses == other.show_incorrect_guesses and
+            self.enable_free_letters == other.enable_free_letters and
+            self.puzzle_options.get("spacer", 0) == other.puzzle_options.get("spacer", 0) and
+            self.puzzle_options.get("may_overlap", False) == other.puzzle_options.get("may_overlap", False)
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "game_mode": self.game_mode,
+            "wordlist_source": self.wordlist_source,
+            "show_incorrect_guesses": self.show_incorrect_guesses,
+            "enable_free_letters": self.enable_free_letters,
+            "puzzle_options": self.puzzle_options,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "GameSettings":
+        """Create from dictionary."""
+        return cls(
+            game_mode=data.get("game_mode", "classic"),
+            wordlist_source=data.get("wordlist_source", "classic.txt"),
+            show_incorrect_guesses=data.get("show_incorrect_guesses", True),
+            enable_free_letters=data.get("enable_free_letters", True),
+            puzzle_options=data.get("puzzle_options", {"spacer": 0, "may_overlap": False}),
+        )
+
+    @classmethod
+    def from_leaderboard(cls, leaderboard: "LeaderboardSettings") -> "GameSettings":
+        """Extract settings from a leaderboard."""
+        return cls(
+            game_mode=leaderboard.game_mode,
+            wordlist_source=leaderboard.wordlist_source,
+            show_incorrect_guesses=leaderboard.show_incorrect_guesses,
+            enable_free_letters=leaderboard.enable_free_letters,
+            puzzle_options=leaderboard.puzzle_options,
+        )
+
+
+@dataclass
+class UserEntry:
+    """Single user entry in a leaderboard (matches challenge user format)."""
+    uid: str
+    username: str
+    word_list: List[str]
+    score: int
+    time: int  # seconds (matches existing 'time' field, not 'time_seconds')
+    timestamp: str
+    word_list_difficulty: Optional[float] = None
+    source_challenge_id: Optional[str] = None  # If entry came from a challenge
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "uid": self.uid,
+            "username": self.username,
+            "word_list": self.word_list,
+            "score": self.score,
+            "time": self.time,
+            "timestamp": self.timestamp,
+        }
+        if self.word_list_difficulty is not None:
+            result["word_list_difficulty"] = self.word_list_difficulty
+        if self.source_challenge_id is not None:
+            result["source_challenge_id"] = self.source_challenge_id
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "UserEntry":
+        """Create from dictionary."""
+        return cls(
+            uid=data["uid"],
+            username=data["username"],
+            word_list=data["word_list"],
+            score=data["score"],
+            time=data.get("time", data.get("time_seconds", 0)),  # Handle both field names
+            timestamp=data["timestamp"],
+            word_list_difficulty=data.get("word_list_difficulty"),
+            source_challenge_id=data.get("source_challenge_id"),
+        )
+
+
+@dataclass
+class LeaderboardSettings:
+    """
+    Unified leaderboard/challenge settings format.
+    
+    This matches the existing challenge settings.json structure with added
+    entry_type field to distinguish between daily, weekly, and challenge entries.
+    The settings fields define what makes this leaderboard unique.
+    """
+    challenge_id: str  # Date-fileId for daily, week-fileId for weekly, UID for challenge
+    entry_type: EntryType  # "daily", "weekly", or "challenge"
+    game_mode: str = "classic"
+    grid_size: int = 8
+    puzzle_options: Dict[str, Any] = field(default_factory=lambda: {"spacer": 0, "may_overlap": False})
+    users: List[UserEntry] = field(default_factory=list)
+    created_at: str = ""
+    version: str = __version__
+    show_incorrect_guesses: bool = True
+    enable_free_letters: bool = True
+    wordlist_source: str = "classic.txt"
+    game_title: str = "Wrdler"
+    max_display_entries: int = MAX_DISPLAY_ENTRIES
+
+    def __post_init__(self):
+        if not self.created_at:
+            self.created_at = datetime.now(timezone.utc).isoformat()
+        if not self.game_title:
+            self.game_title = APP_SETTINGS.get("game_title", "Wrdler")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "challenge_id": self.challenge_id,
+            "entry_type": self.entry_type,
+            "game_mode": self.game_mode,
+            "grid_size": self.grid_size,
+            "puzzle_options": self.puzzle_options,
+            "users": [u.to_dict() for u in self.users],
+            "created_at": self.created_at,
+            "version": self.version,
+            "show_incorrect_guesses": self.show_incorrect_guesses,
+            "enable_free_letters": self.enable_free_letters,
+            "wordlist_source": self.wordlist_source,
+            "game_title": self.game_title,
+            "max_display_entries": self.max_display_entries,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "LeaderboardSettings":
+        """Create from dictionary."""
+        users = [UserEntry.from_dict(u) for u in data.get("users", [])]
+        return cls(
+            challenge_id=data["challenge_id"],
+            entry_type=data.get("entry_type", "challenge"),  # Default for legacy
+            game_mode=data.get("game_mode", "classic"),
+            grid_size=data.get("grid_size", 8),
+            puzzle_options=data.get("puzzle_options", {"spacer": 0, "may_overlap": False}),
+            users=users,
+            created_at=data.get("created_at", ""),
+            version=data.get("version", "0.1.0"),
+            show_incorrect_guesses=data.get("show_incorrect_guesses", True),
+            enable_free_letters=data.get("enable_free_letters", True),
+            wordlist_source=data.get("wordlist_source", "classic.txt"),
+            game_title=data.get("game_title", "Wrdler"),
+            max_display_entries=data.get("max_display_entries", MAX_DISPLAY_ENTRIES),
+        )
+
+    def get_display_users(self) -> List[UserEntry]:
+        """Get users limited to max_display_entries."""
+        return self.users[:self.max_display_entries]
+
+    def get_settings(self) -> GameSettings:
+        """Extract game settings from this leaderboard."""
+        return GameSettings.from_leaderboard(self)
+
+
+def get_current_daily_id() -> str:
+    """Get the date portion of the leaderboard ID for today (UTC)."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+def get_current_weekly_id() -> str:
+    """Get the week portion of the leaderboard ID for the current ISO week."""
+    now = datetime.now(timezone.utc)
+    iso_cal = now.isocalendar()
+    return f"{iso_cal.year}-W{iso_cal.week:02d}"
+
+
+def get_daily_leaderboard_path(date_id: str, file_id: int) -> str:
+    """Get the file path for a daily leaderboard."""
+    return f"{DAILY_LEADERBOARD_PATH}/{date_id}-{file_id}/settings.json"
+
+
+def get_weekly_leaderboard_path(week_id: str, file_id: int) -> str:
+    """Get the file path for a weekly leaderboard."""
+    return f"{WEEKLY_LEADERBOARD_PATH}/{week_id}-{file_id}/settings.json"
+
+
+def _sort_users(users: List[UserEntry]) -> List[UserEntry]:
+    """Sort users by score (desc), time (asc), difficulty (desc)."""
+    return sorted(
+        users,
+        key=lambda u: (
+            -u.score,
+            u.time,
+            -(u.word_list_difficulty or 0)
+        )
+    )
+
+
+def _load_index(repo_id: Optional[str] = None) -> Dict[str, Any]:
+    """Load the leaderboard index."""
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+    
+    data = _get_json_from_repo(repo_id, LEADERBOARD_INDEX_PATH, "dataset")
+    if not data:
+        return {"daily": {}, "weekly": {}}
+    return data
+
+
+def _save_index(index: Dict[str, Any], repo_id: Optional[str] = None) -> bool:
+    """Save the leaderboard index."""
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+    
+    return _upload_json_to_repo(index, repo_id, LEADERBOARD_INDEX_PATH, "dataset")
+
+
+def find_matching_leaderboard(
+    entry_type: EntryType,
+    period_id: str,
+    settings: GameSettings,
+    repo_id: Optional[str] = None
+) -> Tuple[Optional[int], Optional[LeaderboardSettings]]:
+    """
+    Find a leaderboard matching the given settings for a period.
+    
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date string or week identifier
+        settings: Game settings to match
+        repo_id: Repository ID
+    
+    Returns:
+        Tuple of (file_id, leaderboard) or (None, None) if not found
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+    
+    index = _load_index(repo_id)
+    period_entries = index.get(entry_type, {}).get(period_id, [])
+    
+    for entry in period_entries:
+        entry_settings = GameSettings.from_dict(entry)
+        if settings.matches(entry_settings):
+            file_id = entry["file_id"]
+            # Load the actual leaderboard
+            if entry_type == "daily":
+                path = get_daily_leaderboard_path(period_id, file_id)
+            else:
+                path = get_weekly_leaderboard_path(period_id, file_id)
+            
+            data = _get_json_from_repo(repo_id, path, "dataset")
+            if data:
+                return file_id, LeaderboardSettings.from_dict(data)
+    
+    return None, None
+
+
+def create_or_get_leaderboard(
+    entry_type: EntryType,
+    period_id: str,
+    settings: GameSettings,
+    repo_id: Optional[str] = None
+) -> Tuple[int, LeaderboardSettings]:
+    """
+    Get existing leaderboard or create a new one for the settings.
+    
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date string or week identifier
+        settings: Game settings
+        repo_id: Repository ID
+    
+    Returns:
+        Tuple of (file_id, leaderboard)
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+    
+    # Try to find existing
+    file_id, leaderboard = find_matching_leaderboard(entry_type, period_id, settings, repo_id)
+    
+    if leaderboard is not None:
+        return file_id, leaderboard
+    
+    # Create new leaderboard
+    index = _load_index(repo_id)
+    if entry_type not in index:
+        index[entry_type] = {}
+    if period_id not in index[entry_type]:
+        index[entry_type][period_id] = []
+    
+    # Get next file_id
+    existing_ids = [e["file_id"] for e in index[entry_type][period_id]]
+    file_id = max(existing_ids, default=-1) + 1
+    
+    # Create challenge_id
+    challenge_id = f"{period_id}-{file_id}"
+    
+    # Create new leaderboard
+    leaderboard = LeaderboardSettings(
+        challenge_id=challenge_id,
+        entry_type=entry_type,
+        game_mode=settings.game_mode,
+        wordlist_source=settings.wordlist_source,
+        show_incorrect_guesses=settings.show_incorrect_guesses,
+        enable_free_letters=settings.enable_free_letters,
+        puzzle_options=settings.puzzle_options,
+        users=[]
+    )
+    
+    # Update index
+    index_entry = settings.to_dict()
+    index_entry["file_id"] = file_id
+    index[entry_type][period_id].append(index_entry)
+    _save_index(index, repo_id)
+    
+    return file_id, leaderboard
+
+
+def load_leaderboard(
+    entry_type: EntryType,
+    period_id: str,
+    file_id: int,
+    repo_id: Optional[str] = None
+) -> Optional[LeaderboardSettings]:
+    """
+    Load a specific leaderboard by file ID.
+
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date or week identifier
+        file_id: File identifier
+        repo_id: Repository ID (uses HF_REPO_ID if None)
+
+    Returns:
+        LeaderboardSettings object or None if not found
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+
+    if entry_type == "daily":
+        path = get_daily_leaderboard_path(period_id, file_id)
+    elif entry_type == "weekly":
+        path = get_weekly_leaderboard_path(period_id, file_id)
+    else:
+        logger.error(f"Invalid entry_type for leaderboard: {entry_type}")
+        return None
+
+    logger.info(f"?? Loading leaderboard: {path}")
+    data = _get_json_from_repo(repo_id, path, "dataset")
+
+    if not data:
+        logger.info(f"?? No existing leaderboard found at {path}")
+        return None
+
+    return LeaderboardSettings.from_dict(data)
+
+
+def save_leaderboard(
+    leaderboard: LeaderboardSettings,
+    file_id: int,
+    repo_id: Optional[str] = None
+) -> bool:
+    """
+    Save a leaderboard to the repository.
+
+    Args:
+        leaderboard: LeaderboardSettings object to save
+        file_id: File identifier
+        repo_id: Repository ID (uses HF_REPO_ID if None)
+
+    Returns:
+        True if saved successfully, False otherwise
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+
+    # Extract period_id from challenge_id (format: "2025-01-27-0" or "2025-W04-0")
+    parts = leaderboard.challenge_id.rsplit("-", 1)
+    period_id = parts[0] if len(parts) > 1 else leaderboard.challenge_id
+
+    if leaderboard.entry_type == "daily":
+        path = get_daily_leaderboard_path(period_id, file_id)
+    elif leaderboard.entry_type == "weekly":
+        path = get_weekly_leaderboard_path(period_id, file_id)
+    else:
+        logger.error(f"Cannot save leaderboard with entry_type: {leaderboard.entry_type}")
+        return False
+
+    logger.info(f"?? Saving leaderboard: {path}")
+    return _upload_json_to_repo(leaderboard.to_dict(), repo_id, path, "dataset")
+
+
+def create_user_entry(
+    username: str,
+    score: int,
+    time_seconds: int,
+    word_list: List[str],
+    word_list_difficulty: Optional[float] = None,
+    source_challenge_id: Optional[str] = None
+) -> UserEntry:
+    """Create a new user entry."""
+    return UserEntry(
+        uid=generate_uid(),
+        username=username,
+        word_list=word_list,
+        score=score,
+        time=time_seconds,
+        word_list_difficulty=word_list_difficulty,
+        source_challenge_id=source_challenge_id,
+        timestamp=datetime.now(timezone.utc).isoformat()
+    )
+
+
+def check_qualification(
+    leaderboard: Optional[LeaderboardSettings],
+    score: int,
+    time_seconds: int,
+    word_list_difficulty: Optional[float] = None
+) -> bool:
+    """
+    Check if a score qualifies for the leaderboard display (top 20).
+
+    Note: The leaderboard can store more than 20 entries, but only top 20 are displayed.
+    This function checks if the score would be in the top 20.
+
+    Args:
+        leaderboard: Existing leaderboard (or None if new)
+        score: Score to check
+        time_seconds: Time to complete
+        word_list_difficulty: Difficulty score
+
+    Returns:
+        True if qualifies for display, False otherwise
+    """
+    if leaderboard is None or len(leaderboard.users) < MAX_DISPLAY_ENTRIES:
+        return True
+
+    # Get the 20th entry (last displayed)
+    display_users = leaderboard.get_display_users()
+    if len(display_users) < MAX_DISPLAY_ENTRIES:
+        return True
+
+    lowest = display_users[-1]
+
+    # Primary: higher score qualifies
+    if score > lowest.score:
+        return True
+    if score < lowest.score:
+        return False
+
+    # Secondary: faster time qualifies (for equal score)
+    if time_seconds < lowest.time:
+        return True
+    if time_seconds > lowest.time:
+        return False
+
+    # Tertiary: higher difficulty qualifies (for equal score and time)
+    entry_diff = word_list_difficulty or 0
+    lowest_diff = lowest.word_list_difficulty or 0
+    return entry_diff > lowest_diff
+
+
+def submit_to_leaderboard(
+    entry_type: EntryType,
+    period_id: str,
+    user_entry: UserEntry,
+    settings: GameSettings,
+    repo_id: Optional[str] = None
+) -> Tuple[bool, Optional[int]]:
+    """
+    Submit a user entry to a leaderboard if it qualifies.
+
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date or week identifier
+        user_entry: UserEntry to submit
+        settings: Game settings to match leaderboard
+        repo_id: Repository ID
+
+    Returns:
+        Tuple of (success, rank) where rank is 1-indexed position or None if didn't qualify
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+
+    # Get or create matching leaderboard
+    file_id, leaderboard = create_or_get_leaderboard(entry_type, period_id, settings, repo_id)
+
+    # Check qualification for display
+    qualifies = check_qualification(
+        leaderboard,
+        user_entry.score,
+        user_entry.time,
+        user_entry.word_list_difficulty
+    )
+
+    if not qualifies:
+        logger.info(f"? Score {user_entry.score} did not qualify for top {MAX_DISPLAY_ENTRIES} in {period_id}")
+        return False, None
+
+    # Add entry and sort
+    leaderboard.users.append(user_entry)
+    leaderboard.users = _sort_users(leaderboard.users)
+
+    # Find rank (1-indexed) - check if in display range
+    rank = None
+    for i, u in enumerate(leaderboard.users[:MAX_DISPLAY_ENTRIES]):
+        if u.uid == user_entry.uid:
+            rank = i + 1
+            break
+
+    if rank is None:
+        # Entry was sorted out of top 20
+        logger.info(f"? Score {user_entry.score} was sorted out of top {MAX_DISPLAY_ENTRIES}")
+        # Still save the entry (stored but not displayed)
+        save_leaderboard(leaderboard, file_id, repo_id)
+        return False, None
+
+    # Save leaderboard
+    if save_leaderboard(leaderboard, file_id, repo_id):
+        logger.info(f"? Added to {entry_type} leaderboard at rank {rank}")
+        return True, rank
+    else:
+        logger.error(f"? Failed to save leaderboard {period_id}")
+        return False, None
+
+
+def submit_score_to_all_leaderboards(
+    username: str,
+    score: int,
+    time_seconds: int,
+    word_list: List[str],
+    settings: GameSettings,
+    word_list_difficulty: Optional[float] = None,
+    source_challenge_id: Optional[str] = None,
+    repo_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Submit a score to both daily and weekly leaderboards matching the settings.
+
+    This is the main entry point for game completions.
+
+    Args:
+        username: Player name
+        score: Final score
+        time_seconds: Time to complete
+        word_list: Words played
+        settings: Game settings (determines which leaderboard)
+        word_list_difficulty: Difficulty score
+        source_challenge_id: If from a challenge, the original challenge_id
+        repo_id: Repository ID
+
+    Returns:
+        Dict with results:
+        {
+            "daily": {"qualified": bool, "rank": int|None, "id": str},
+            "weekly": {"qualified": bool, "rank": int|None, "id": str},
+            "entry_uid": str,
+            "settings": {...}
+        }
+    """
+    logger.info(f"?? Submitting score: {score} by {username} with settings: {settings.game_mode}")
+
+    # Get current period IDs
+    daily_id = get_current_daily_id()
+    weekly_id = get_current_weekly_id()
+
+    # Create user entry for daily
+    daily_entry = create_user_entry(
+        username=username,
+        score=score,
+        time_seconds=time_seconds,
+        word_list=word_list,
+        word_list_difficulty=word_list_difficulty,
+        source_challenge_id=source_challenge_id
+    )
+
+    # Submit to daily
+    daily_qualified, daily_rank = submit_to_leaderboard(
+        "daily", daily_id, daily_entry, settings, repo_id
+    )
+
+    # Create separate user entry for weekly (different UID)
+    weekly_entry = create_user_entry(
+        username=username,
+        score=score,
+        time_seconds=time_seconds,
+        word_list=word_list,
+        word_list_difficulty=word_list_difficulty,
+        source_challenge_id=source_challenge_id
+    )
+
+    # Submit to weekly
+    weekly_qualified, weekly_rank = submit_to_leaderboard(
+        "weekly", weekly_id, weekly_entry, settings, repo_id
+    )
+
+    results = {
+        "daily": {"qualified": daily_qualified, "rank": daily_rank, "id": daily_id},
+        "weekly": {"qualified": weekly_qualified, "rank": weekly_rank, "id": weekly_id},
+        "entry_uid": daily_entry.uid,
+        "settings": settings.to_dict()
+    }
+
+    logger.info(f"?? Leaderboard results: {results}")
+    return results
+
+
+def get_leaderboards_for_settings(
+    entry_type: EntryType,
+    period_id: str,
+    settings: GameSettings,
+    repo_id: Optional[str] = None
+) -> Optional[LeaderboardSettings]:
+    """
+    Get leaderboard matching specific settings for a period.
+    
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date or week identifier
+        settings: Game settings to match
+        repo_id: Repository ID
+    
+    Returns:
+        LeaderboardSettings or None if not found
+    """
+    _, leaderboard = find_matching_leaderboard(entry_type, period_id, settings, repo_id)
+    return leaderboard
+
+
+def get_last_n_daily_leaderboards(
+    n: int = 7,
+    settings: Optional[GameSettings] = None,
+    repo_id: Optional[str] = None
+) -> List[Tuple[str, Optional[LeaderboardSettings]]]:
+    """
+    Get the last N days of daily leaderboards for specific settings.
+
+    Args:
+        n: Number of days to retrieve
+        settings: Game settings to filter by (None = default settings)
+        repo_id: Repository ID
+
+    Returns:
+        List of tuples (date_id, leaderboard) in reverse chronological order
+    """
+    if settings is None:
+        settings = GameSettings()
+    
+    results = []
+    today = datetime.now(timezone.utc).date()
+
+    for i in range(n):
+        date = today - timedelta(days=i)
+        date_id = date.strftime("%Y-%m-%d")
+        leaderboard = get_leaderboards_for_settings("daily", date_id, settings, repo_id)
+        results.append((date_id, leaderboard))
+
+    return results
+
+
+def list_available_periods(
+    entry_type: EntryType,
+    limit: int = 30,
+    repo_id: Optional[str] = None
+) -> List[str]:
+    """
+    List available period IDs from the index.
+
+    Args:
+        entry_type: "daily" or "weekly"
+        limit: Maximum number of IDs to return
+        repo_id: Repository ID
+
+    Returns:
+        List of period IDs in reverse chronological order
+    """
+    index = _load_index(repo_id)
+    periods = list(index.get(entry_type, {}).keys())
+    periods.sort(reverse=True)
+    return periods[:limit]
+
+
+def list_settings_for_period(
+    entry_type: EntryType,
+    period_id: str,
+    repo_id: Optional[str] = None
+) -> List[Dict[str, Any]]:
+    """
+    List all settings combinations available for a period.
+    
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date or week identifier
+        repo_id: Repository ID
+    
+    Returns:
+        List of settings dictionaries with file_id
+    """
+    index = _load_index(repo_id)
+    return index.get(entry_type, {}).get(period_id, [])
+```
+
+---
+
+## 6. Implementation Steps
+
+### Phase 1: Core Leaderboard Module (v0.2.0-alpha)
+
+| Step | Task | Files | Effort |
+|------|------|-------|--------|
+| 1.1 | Create `wrdler/leaderboard.py` with `GameSettings` and data models | NEW | 2h |
+| 1.2 | Implement index management (`_load_index`, `_save_index`) | leaderboard.py | 1h |
+| 1.3 | Implement `find_matching_leaderboard()` and `create_or_get_leaderboard()` | leaderboard.py | 1.5h |
+| 1.4 | Implement `check_qualification()` and sorting | leaderboard.py | 1h |
+| 1.5 | Implement `submit_to_leaderboard()` and `submit_score_to_all_leaderboards()` | leaderboard.py | 1h |
+| 1.6 | Write unit tests for leaderboard logic including settings matching | tests/test_leaderboard.py | 2h |
+
+### Phase 2: UI Integration (v0.2.0-beta)
+
+| Step | Task | Files | Effort |
+|------|------|-------|--------|
+| 2.1 | Create `wrdler/leaderboard_page.py` with settings filtering | NEW | 3h |
+| 2.2 | Add leaderboard navigation to `ui.py` sidebar | ui.py | 1h |
+| 2.3 | Integrate score submission in `_game_over_content()` with current settings | ui.py | 2h |
+| 2.4 | Add leaderboard results display in game over dialog | ui.py | 1h |
+| 2.5 | Style leaderboard tables to match ocean theme | leaderboard_page.py | 1h |
+
+### Phase 3: Challenge Format Migration (v0.2.0-beta)
+
+| Step | Task | Files | Effort |
+|------|------|-------|--------|
+| 3.1 | Add `entry_type` field to existing challenge saves | game_storage.py | 1h |
+| 3.2 | Update challenge loading to handle `entry_type` | game_storage.py | 0.5h |
+| 3.3 | Test backward compatibility with old challenges | Manual | 1h |
+
+### Phase 4: Testing & Polish (v0.2.0-rc)
+
+| Step | Task | Files | Effort |
+|------|------|-------|--------|
+| 4.1 | Integration testing with HuggingFace | Manual | 2h |
+| 4.2 | Add caching for leaderboard data | leaderboard.py | 1h |
+| 4.3 | Add error handling and retry logic | leaderboard.py | 1h |
+| 4.4 | Update documentation | README.md, specs/ | 1h |
+| 4.5 | Version bump and release notes | pyproject.toml, __init__.py | 0.5h |
+
+---
+
+## 7. Version Changes
+
+### pyproject.toml
+
+```toml
+[project]
+name = "wrdler"
+version = "0.2.0"  # Updated from 0.1.0
+description = "Wrdler vocabulary puzzle game with daily/weekly leaderboards"
+```
+
+### wrdler/__init__.py
+
+```python
+__version__ = "0.2.0"  # Updated from existing version
+```
+
+### wrdler/game_storage.py
+
+```python
+__version__ = "0.2.0"  # Updated from 0.1.5
+```
+
+### wrdler/leaderboard.py (NEW)
+
+```python
+__version__ = "0.2.0"
+```
+
+### wrdler/leaderboard_page.py (NEW)
+
+```python
+__version__ = "0.2.0"
+```
+
+---
+
+## 8. File Changes Summary
+
+### New Files
+
+| File | Purpose |
+|------|---------|
+| `wrdler/leaderboard.py` | Core leaderboard logic with unified format |
+| `wrdler/leaderboard_page.py` | Streamlit leaderboard page |
+| `tests/test_leaderboard.py` | Unit tests for leaderboard |
+| `specs/leaderboard_spec.md` | This specification |
+
+### Modified Files
+
+| File | Changes |
+|------|---------|
+| `pyproject.toml` | Version bump to 0.2.0 |
+| `wrdler/__init__.py` | Version bump, add leaderboard exports |
+| `wrdler/game_storage.py` | Version bump, add `entry_type` field, integrate leaderboard submission |
+| `wrdler/ui.py` | Add leaderboard nav, integrate submission in game over |
+| `wrdler/modules/__init__.py` | Export new functions if needed |
+
+---
+
+## 9. API Reference
+
+### Public Functions in `wrdler/leaderboard.py`
+
+```python
+def submit_score_to_all_leaderboards(
+    username: str,
+    score: int,
+    time_seconds: int,
+    game_mode: str,
+    wordlist_source: str,
+    word_list: List[str],
+    word_list_difficulty: Optional[float] = None,
+    source_challenge_id: Optional[str] = None,
+    repo_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """Main entry point for submitting scores after game completion."""
+
+def load_leaderboard(
+    entry_type: EntryType,
+    period_id: str,
+    file_id: int,
+    repo_id: Optional[str] = None
+) -> Optional[LeaderboardSettings]:
+    """Load a specific leaderboard."""
+
+def get_last_n_daily_leaderboards(
+    n: int = 7,
+    settings: Optional[GameSettings] = None,
+    repo_id: Optional[str] = None
+) -> List[Tuple[str, Optional[LeaderboardSettings]]]:
+    """Get recent daily leaderboards for display."""
+
+def get_current_daily_id() -> str:
+    """Get today's leaderboard ID (challenge_id)."""
+
+def get_current_weekly_id() -> str:
+    """Get this week's leaderboard ID (challenge_id)."""
+```
+
+---
+
+## 10. UI Components
+
+### 10.1 Sidebar Navigation
+
+Add to `_render_sidebar()` in `ui.py`:
+
+```python
+st.header("Navigation")
+if st.button("?? Leaderboards", use_container_width=True):
+    st.session_state["show_leaderboard_page"] = True
+    st.rerun()
+```
+
+### 10.2 Game Over Integration
+
+Modify `_game_over_content()` in `ui.py` to:
+
+1. Call `submit_score_to_all_leaderboards()` after generating share link
+2. Display qualification results:
+
+```python
+# After score submission
+if results["daily"]["qualified"]:
+    st.success(f"?? You ranked #{results['daily']['rank']} on today's leaderboard!")
+if results["weekly"]["qualified"]:
+    st.success(f"?? You ranked #{results['weekly']['rank']} on this week's leaderboard!")
+```
+
+### 10.3 Leaderboard Page Routing
+
+In `run_app()`:
+
+```python
+# Check if leaderboard page should be shown
+if st.session_state.get("show_leaderboard_page", False):
+    from wrdler.leaderboard_page import render_leaderboard_page
+    render_leaderboard_page()
+    if st.button("?? Back to Game"):
+        st.session_state["show_leaderboard_page"] = False
+        st.rerun()
+    return  # Don't render game UI
+```
+
+---
+
+## 11. Testing Requirements
+
+### Unit Tests (`tests/test_leaderboard.py`)
+
+```python
+class TestUserEntry:
+    def test_create_entry(self): ...
+    def test_to_dict_roundtrip(self): ...
+    def test_from_legacy_time_seconds_field(self): ...
+
+class TestLeaderboardSettings:
+    def test_create_leaderboard(self): ...
+    def test_entry_type_values(self): ...
+    def test_get_display_users_limit(self): ...
+    def test_format_matches_challenge(self): ...
+
+class TestQualification:
+    def test_qualify_empty_leaderboard(self): ...
+    def test_qualify_not_full(self): ...
+    def test_qualify_by_score(self): ...
+    def test_qualify_by_time_tiebreaker(self): ...
+    def test_qualify_by_difficulty_tiebreaker(self): ...
+    def test_not_qualify_lower_score(self): ...
+
+class TestDateIds:
+    def test_daily_id_format(self): ...
+    def test_weekly_id_format(self): ...
+
+class TestUnifiedFormat:
+    def test_leaderboard_matches_challenge_structure(self): ...
+    def test_entry_type_field_present(self): ...
+    def test_challenge_id_as_primary_identifier(self): ...
+```
+
+
+### Integration Tests
+
+- Test full flow: game completion ? leaderboard submission ? retrieval
+- Test with mock HuggingFace repository
+- Test concurrent submissions (edge case)
+- Test backward compatibility with legacy challenge files (no entry_type)
+
+---
+
+## 12. Migration Notes
+
+### Backward Compatibility
+
+- Existing challenges continue to work unchanged (entry_type defaults to "challenge")
+- No changes to `shortener.json` format
+- Challenge `settings.json` format is extended (new fields are optional)
+
+### Schema Evolution
+
+| Version | Changes |
+|---------|---------|
+| 0.1.x | Original challenge format |
+| 0.2.0 | Added `entry_type`, `max_display_entries`, `source_challenge_id` fields |
+
+### Data Migration
+
+- No migration required for existing challenges
+- New leaderboard files use unified format from start
+- Legacy challenges without `entry_type` default to `"challenge"`
+
+### Rollback Plan
+
+1. Remove leaderboard imports from `ui.py`
+2. Remove sidebar navigation button
+3. Remove game over submission calls
+4. Optionally: delete `leaderboards/` directory from HF repo
+
+---
+
+## Appendix A: Example Daily Leaderboard JSON (Settings-Based)
+
+```json
+{
+  "challenge_id": "2025-01-27-0",
+  "entry_type": "daily",
+  "game_mode": "classic",
+  "grid_size": 8,
+  "puzzle_options": {
+    "spacer": 0,
+    "may_overlap": false
+  },
+  "users": [
+    {
+      "uid": "20251130T190249Z-0XLG5O",
+      "username": "Charles",
+      "word_list": ["CHEER", "PLENTY", "REAL", "ARRIVE", "DEAF", "DAILY"],
+      "word_list_difficulty": 117.48,
+      "score": 39,
+      "time": 132,
+      "timestamp": "2025-11-30T19:02:49.544933+00:00",
+      "source_challenge_id": null
+    }
+  ],
+  "created_at": "2025-11-30T19:02:49.544933+00:00",
+  "version": "0.2.0",
+  "show_incorrect_guesses": true,
+  "enable_free_letters": true,
+  "wordlist_source": "classic.txt",
+  "game_title": "Wrdler Gradio AI",
+  "max_display_entries": 20
+}
+```
+
+---
+
+## Appendix B: Example Index JSON
+
+```json
+{
+  "daily": {
+    "2025-01-27": [
+      {
+        "file_id": 0,
+        "game_mode": "classic",
+        "wordlist_source": "classic.txt",
+        "show_incorrect_guesses": true,
+        "enable_free_letters": true,
+        "puzzle_options": {"spacer": 0, "may_overlap": false}
+      },
+      {
+        "file_id": 1,
+        "game_mode": "easy",
+        "wordlist_source": "easy.txt",
+        "show_incorrect_guesses": true,
+        "enable_free_letters": true,
+        "puzzle_options": {"spacer": 0, "may_overlap": false}
+      }
+    ]
+  },
+  "weekly": {
+    "2025-W04": [
+      {
+        "file_id": 0,
+        "game_mode": "classic",
+        "wordlist_source": "classic.txt",
+        "show_incorrect_guesses": true,
+        "enable_free_letters": true,
+        "puzzle_options": {"spacer": 0, "may_overlap": false}
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Appendix C: Entry Type Comparison (Updated)
+
+| Field | daily | weekly | challenge |
+|-------|-------|--------|-----------|
+| `challenge_id` format | `"2025-01-27-0"` | `"2025-W04-0"` | `"20251130T190249Z-ABC123"` |
+| `entry_type` | `"daily"` | `"weekly"` | `"challenge"` |
+| Storage path | `leaderboards/daily/{date}-{file_id}/settings.json` | `leaderboards/weekly/{week}-{file_id}/settings.json` | `games/{id}/settings.json` |
+| Reset frequency | Daily (UTC midnight) | Weekly (Monday UTC midnight) | Never (permanent) |
+| Settings-based | Yes (separate folder per settings) | Yes (separate folder per settings) | N/A (settings fixed per challenge) |
+| `max_display_entries` | 20 | 20 | N/A (all users shown) |
+
+---
+
+*End of Specification*

tests/test_leaderboard.py

@@ -0,0 +1,525 @@
+# tests/test_leaderboard.py
+"""
+Unit tests for the Wrdler Leaderboard System.
+
+Tests cover:
+- UserEntry and LeaderboardSettings dataclasses
+- Qualification logic
+- Sorting functions
+- Date/week ID generation
+"""
+
+import pytest
+from datetime import datetime, timezone, timedelta
+from unittest.mock import patch, MagicMock
+
+from wrdler.leaderboard import (
+    UserEntry,
+    LeaderboardSettings,
+    get_current_daily_id,
+    get_current_weekly_id,
+    get_daily_leaderboard_path,
+    get_weekly_leaderboard_path,
+    _sort_users,
+    check_qualification,
+    create_user_entry,
+    MAX_DISPLAY_ENTRIES,
+)
+
+
+class TestUserEntry:
+    """Tests for UserEntry dataclass."""
+
+    def test_create_entry(self):
+        """Test basic UserEntry creation."""
+        entry = UserEntry(
+            uid="test-uid-123",
+            username="TestPlayer",
+            word_list=["WORD", "TEST", "GAME", "PLAY", "SCORE", "FINAL"],
+            score=42,
+            time=180,
+            timestamp="2025-01-27T12:00:00+00:00",
+        )
+        assert entry.uid == "test-uid-123"
+        assert entry.username == "TestPlayer"
+        assert len(entry.word_list) == 6
+        assert entry.score == 42
+        assert entry.time == 180
+        assert entry.word_list_difficulty is None
+        assert entry.source_challenge_id is None
+
+    def test_to_dict_basic(self):
+        """Test to_dict without optional fields."""
+        entry = UserEntry(
+            uid="test-uid",
+            username="Player",
+            word_list=["A", "B", "C", "D", "E", "F"],
+            score=30,
+            time=120,
+            timestamp="2025-01-27T12:00:00+00:00",
+        )
+        d = entry.to_dict()
+        
+        assert d["uid"] == "test-uid"
+        assert d["username"] == "Player"
+        assert d["score"] == 30
+        assert d["time"] == 120
+        assert "word_list_difficulty" not in d
+        assert "source_challenge_id" not in d
+
+    def test_to_dict_with_optional_fields(self):
+        """Test to_dict with optional fields."""
+        entry = UserEntry(
+            uid="test-uid",
+            username="Player",
+            word_list=["A", "B", "C", "D", "E", "F"],
+            score=30,
+            time=120,
+            timestamp="2025-01-27T12:00:00+00:00",
+            word_list_difficulty=117.5,
+            source_challenge_id="challenge-123",
+        )
+        d = entry.to_dict()
+        
+        assert d["word_list_difficulty"] == 117.5
+        assert d["source_challenge_id"] == "challenge-123"
+
+    def test_from_dict_roundtrip(self):
+        """Test to_dict/from_dict roundtrip."""
+        original = UserEntry(
+            uid="test-uid",
+            username="Player",
+            word_list=["A", "B", "C", "D", "E", "F"],
+            score=30,
+            time=120,
+            timestamp="2025-01-27T12:00:00+00:00",
+            word_list_difficulty=100.0,
+        )
+        d = original.to_dict()
+        restored = UserEntry.from_dict(d)
+        
+        assert restored.uid == original.uid
+        assert restored.username == original.username
+        assert restored.score == original.score
+        assert restored.time == original.time
+        assert restored.word_list_difficulty == original.word_list_difficulty
+
+    def test_from_dict_legacy_time_seconds(self):
+        """Test from_dict handles legacy 'time_seconds' field."""
+        data = {
+            "uid": "test",
+            "username": "Player",
+            "word_list": ["A", "B", "C", "D", "E", "F"],
+            "score": 30,
+            "time_seconds": 150,  # Legacy field name
+            "timestamp": "2025-01-27T12:00:00+00:00",
+        }
+        entry = UserEntry.from_dict(data)
+        assert entry.time == 150
+
+
+class TestLeaderboardSettings:
+    """Tests for LeaderboardSettings dataclass."""
+
+    def test_create_leaderboard(self):
+        """Test basic LeaderboardSettings creation."""
+        lb = LeaderboardSettings(
+            challenge_id="2025-01-27",
+            entry_type="daily",
+        )
+        assert lb.challenge_id == "2025-01-27"
+        assert lb.entry_type == "daily"
+        assert lb.game_mode == "classic"
+        assert lb.grid_size == 8
+        assert len(lb.users) == 0
+        assert lb.max_display_entries == MAX_DISPLAY_ENTRIES
+
+    def test_entry_type_values(self):
+        """Test valid entry_type values."""
+        for entry_type in ["daily", "weekly", "challenge"]:
+            lb = LeaderboardSettings(
+                challenge_id="test",
+                entry_type=entry_type,
+            )
+            assert lb.entry_type == entry_type
+
+    def test_get_display_users_limit(self):
+        """Test get_display_users respects max_display_entries."""
+        users = [
+            UserEntry(
+                uid=f"uid-{i}",
+                username=f"Player{i}",
+                word_list=["A", "B", "C", "D", "E", "F"],
+                score=100 - i,
+                time=60 + i,
+                timestamp="2025-01-27T12:00:00+00:00",
+            )
+            for i in range(25)  # More than MAX_DISPLAY_ENTRIES
+        ]
+        
+        lb = LeaderboardSettings(
+            challenge_id="test",
+            entry_type="daily",
+            users=users,
+        )
+        
+        display_users = lb.get_display_users()
+        assert len(display_users) == MAX_DISPLAY_ENTRIES
+        # Should be first 20 (already sorted by creation)
+        assert display_users[0].uid == "uid-0"
+
+    def test_to_dict_and_from_dict(self):
+        """Test LeaderboardSettings serialization roundtrip."""
+        user = UserEntry(
+            uid="test-uid",
+            username="Player",
+            word_list=["A", "B", "C", "D", "E", "F"],
+            score=50,
+            time=100,
+            timestamp="2025-01-27T12:00:00+00:00",
+        )
+        
+        lb = LeaderboardSettings(
+            challenge_id="2025-01-27",
+            entry_type="daily",
+            game_mode="easy",
+            users=[user],
+            wordlist_source="test.txt",
+        )
+        
+        d = lb.to_dict()
+        restored = LeaderboardSettings.from_dict(d)
+        
+        assert restored.challenge_id == lb.challenge_id
+        assert restored.entry_type == lb.entry_type
+        assert restored.game_mode == lb.game_mode
+        assert len(restored.users) == 1
+        assert restored.wordlist_source == lb.wordlist_source
+
+    def test_format_matches_challenge_structure(self):
+        """Test that leaderboard format matches challenge settings.json structure."""
+        lb = LeaderboardSettings(
+            challenge_id="2025-01-27",
+            entry_type="daily",
+            game_mode="classic",
+            grid_size=8,
+            wordlist_source="classic.txt",
+        )
+        d = lb.to_dict()
+        
+        # Key fields that should match challenge format
+        assert "challenge_id" in d
+        assert "entry_type" in d
+        assert "game_mode" in d
+        assert "grid_size" in d
+        assert "puzzle_options" in d
+        assert "users" in d
+        assert "created_at" in d
+        assert "version" in d
+        assert "show_incorrect_guesses" in d
+        assert "enable_free_letters" in d
+        assert "wordlist_source" in d
+
+
+class TestQualification:
+    """Tests for qualification logic."""
+
+    def test_qualify_empty_leaderboard(self):
+        """Test that any score qualifies for empty leaderboard."""
+        assert check_qualification(None, 1, 999) is True
+
+    def test_qualify_not_full(self):
+        """Test qualification when leaderboard is not full."""
+        users = [
+            UserEntry(
+                uid=f"uid-{i}",
+                username=f"Player{i}",
+                word_list=["A", "B", "C", "D", "E", "F"],
+                score=50,
+                time=100,
+                timestamp="2025-01-27T12:00:00+00:00",
+            )
+            for i in range(10)  # Less than MAX_DISPLAY_ENTRIES
+        ]
+        
+        lb = LeaderboardSettings(
+            challenge_id="test",
+            entry_type="daily",
+            users=users,
+        )
+        
+        # Any score should qualify
+        assert check_qualification(lb, 1, 999) is True
+
+    def test_qualify_by_score(self):
+        """Test qualification by higher score."""
+        users = [
+            UserEntry(
+                uid=f"uid-{i}",
+                username=f"Player{i}",
+                word_list=["A", "B", "C", "D", "E", "F"],
+                score=50 - i,  # Scores from 50 down to 31
+                time=100,
+                timestamp="2025-01-27T12:00:00+00:00",
+            )
+            for i in range(20)
+        ]
+        
+        lb = LeaderboardSettings(
+            challenge_id="test",
+            entry_type="daily",
+            users=users,
+        )
+        
+        # Higher than lowest (31) should qualify
+        assert check_qualification(lb, 32, 100) is True
+        # Equal to lowest but faster time should qualify
+        assert check_qualification(lb, 31, 99) is True
+        # Lower than lowest should not qualify
+        assert check_qualification(lb, 30, 100) is False
+
+    def test_qualify_by_time_tiebreaker(self):
+        """Test qualification using time as tiebreaker."""
+        users = [
+            UserEntry(
+                uid=f"uid-{i}",
+                username=f"Player{i}",
+                word_list=["A", "B", "C", "D", "E", "F"],
+                score=50,  # All same score
+                time=100 + i,  # Times from 100 to 119
+                timestamp="2025-01-27T12:00:00+00:00",
+            )
+            for i in range(20)
+        ]
+        
+        lb = LeaderboardSettings(
+            challenge_id="test",
+            entry_type="daily",
+            users=users,
+        )
+        
+        # Same score but faster than slowest (119) should qualify
+        assert check_qualification(lb, 50, 118) is True
+        # Same score and slower should not qualify
+        assert check_qualification(lb, 50, 120) is False
+
+    def test_qualify_by_difficulty_tiebreaker(self):
+        """Test qualification using difficulty as final tiebreaker."""
+        users = [
+            UserEntry(
+                uid=f"uid-{i}",
+                username=f"Player{i}",
+                word_list=["A", "B", "C", "D", "E", "F"],
+                score=50,  # All same score
+                time=100,  # All same time
+                timestamp="2025-01-27T12:00:00+00:00",
+                word_list_difficulty=100.0 - i,  # Difficulties from 100 to 81
+            )
+            for i in range(20)
+        ]
+        
+        lb = LeaderboardSettings(
+            challenge_id="test",
+            entry_type="daily",
+            users=users,
+        )
+        
+        # Same score/time but higher difficulty than lowest (81) should qualify
+        assert check_qualification(lb, 50, 100, 82.0) is True
+        # Lower difficulty should not qualify
+        assert check_qualification(lb, 50, 100, 80.0) is False
+
+    def test_not_qualify_lower_score(self):
+        """Test that lower score doesn't qualify for full leaderboard."""
+        users = [
+            UserEntry(
+                uid=f"uid-{i}",
+                username=f"Player{i}",
+                word_list=["A", "B", "C", "D", "E", "F"],
+                score=100,  # All high scores
+                time=60,
+                timestamp="2025-01-27T12:00:00+00:00",
+            )
+            for i in range(20)
+        ]
+        
+        lb = LeaderboardSettings(
+            challenge_id="test",
+            entry_type="daily",
+            users=users,
+        )
+        
+        # Much lower score should not qualify
+        assert check_qualification(lb, 50, 60) is False
+
+
+class TestDateIds:
+    """Tests for date/week ID generation."""
+
+    def test_daily_id_format(self):
+        """Test daily ID format is YYYY-MM-DD."""
+        daily_id = get_current_daily_id()
+        # Should match pattern YYYY-MM-DD
+        assert len(daily_id) == 10
+        assert daily_id[4] == "-"
+        assert daily_id[7] == "-"
+        
+        # Parse to verify it's a valid date
+        date = datetime.strptime(daily_id, "%Y-%m-%d")
+        assert date is not None
+
+    def test_weekly_id_format(self):
+        """Test weekly ID format is YYYY-Www."""
+        weekly_id = get_current_weekly_id()
+        # Should match pattern YYYY-Www
+        assert "-W" in weekly_id
+        parts = weekly_id.split("-W")
+        assert len(parts) == 2
+        assert len(parts[0]) == 4  # Year
+        assert len(parts[1]) == 2  # Week number with leading zero
+
+    def test_daily_path(self):
+        """Test daily leaderboard path generation."""
+        path = get_daily_leaderboard_path("2025-01-27")
+        assert path == "leaderboards/daily/2025-01-27.json"
+
+    def test_weekly_path(self):
+        """Test weekly leaderboard path generation."""
+        path = get_weekly_leaderboard_path("2025-W04")
+        assert path == "leaderboards/weekly/2025-W04.json"
+
+
+class TestSorting:
+    """Tests for user sorting."""
+
+    def test_sort_by_score_desc(self):
+        """Test users are sorted by score descending."""
+        users = [
+            UserEntry(uid="1", username="A", word_list=[], score=30, time=100, timestamp=""),
+            UserEntry(uid="2", username="B", word_list=[], score=50, time=100, timestamp=""),
+            UserEntry(uid="3", username="C", word_list=[], score=40, time=100, timestamp=""),
+        ]
+        
+        sorted_users = _sort_users(users)
+        
+        assert sorted_users[0].score == 50
+        assert sorted_users[1].score == 40
+        assert sorted_users[2].score == 30
+
+    def test_sort_by_time_asc_for_equal_score(self):
+        """Test users with equal score are sorted by time ascending."""
+        users = [
+            UserEntry(uid="1", username="A", word_list=[], score=50, time=120, timestamp=""),
+            UserEntry(uid="2", username="B", word_list=[], score=50, time=80, timestamp=""),
+            UserEntry(uid="3", username="C", word_list=[], score=50, time=100, timestamp=""),
+        ]
+        
+        sorted_users = _sort_users(users)
+        
+        assert sorted_users[0].time == 80
+        assert sorted_users[1].time == 100
+        assert sorted_users[2].time == 120
+
+    def test_sort_by_difficulty_desc_for_equal_score_and_time(self):
+        """Test users with equal score and time are sorted by difficulty descending."""
+        users = [
+            UserEntry(uid="1", username="A", word_list=[], score=50, time=100, timestamp="", word_list_difficulty=80.0),
+            UserEntry(uid="2", username="B", word_list=[], score=50, time=100, timestamp="", word_list_difficulty=120.0),
+            UserEntry(uid="3", username="C", word_list=[], score=50, time=100, timestamp="", word_list_difficulty=100.0),
+        ]
+        
+        sorted_users = _sort_users(users)
+        
+        assert sorted_users[0].word_list_difficulty == 120.0
+        assert sorted_users[1].word_list_difficulty == 100.0
+        assert sorted_users[2].word_list_difficulty == 80.0
+
+
+class TestCreateUserEntry:
+    """Tests for create_user_entry helper."""
+
+    def test_create_user_entry_basic(self):
+        """Test creating a user entry with basic fields."""
+        entry = create_user_entry(
+            username="TestPlayer",
+            score=45,
+            time_seconds=150,
+            word_list=["A", "B", "C", "D", "E", "F"],
+        )
+        
+        assert entry.username == "TestPlayer"
+        assert entry.score == 45
+        assert entry.time == 150
+        assert len(entry.word_list) == 6
+        assert entry.uid is not None  # Auto-generated
+        assert entry.timestamp is not None  # Auto-generated
+
+    def test_create_user_entry_with_optional_fields(self):
+        """Test creating a user entry with optional fields."""
+        entry = create_user_entry(
+            username="TestPlayer",
+            score=45,
+            time_seconds=150,
+            word_list=["A", "B", "C", "D", "E", "F"],
+            word_list_difficulty=110.5,
+            source_challenge_id="challenge-xyz",
+        )
+        
+        assert entry.word_list_difficulty == 110.5
+        assert entry.source_challenge_id == "challenge-xyz"
+
+
+class TestUnifiedFormat:
+    """Tests for unified format consistency."""
+
+    def test_leaderboard_matches_challenge_structure(self):
+        """Test leaderboard to_dict matches expected challenge structure."""
+        lb = LeaderboardSettings(
+            challenge_id="2025-01-27",
+            entry_type="daily",
+        )
+        d = lb.to_dict()
+        
+        # All challenge fields should be present
+        required_fields = [
+            "challenge_id",
+            "entry_type",
+            "game_mode",
+            "grid_size",
+            "puzzle_options",
+            "users",
+            "created_at",
+            "version",
+            "show_incorrect_guesses",
+            "enable_free_letters",
+            "wordlist_source",
+            "game_title",
+            "max_display_entries",
+        ]
+        
+        for field in required_fields:
+            assert field in d, f"Missing field: {field}"
+
+    def test_entry_type_field_present(self):
+        """Test entry_type is always present in serialized output."""
+        for entry_type in ["daily", "weekly", "challenge"]:
+            lb = LeaderboardSettings(
+                challenge_id="test",
+                entry_type=entry_type,
+            )
+            d = lb.to_dict()
+            assert d["entry_type"] == entry_type
+
+    def test_challenge_id_as_primary_identifier(self):
+        """Test challenge_id serves as primary identifier for all types."""
+        # Daily uses date format
+        daily = LeaderboardSettings(challenge_id="2025-01-27", entry_type="daily")
+        assert daily.challenge_id == "2025-01-27"
+        
+        # Weekly uses week format
+        weekly = LeaderboardSettings(challenge_id="2025-W04", entry_type="weekly")
+        assert weekly.challenge_id == "2025-W04"
+        
+        # Challenge uses UID format
+        challenge = LeaderboardSettings(challenge_id="20251130T190249Z-ABCDEF", entry_type="challenge")
+        assert challenge.challenge_id == "20251130T190249Z-ABCDEF"

wrdler/__init__.py

@@ -6,7 +6,8 @@ Key differences from BattleWords:
 - One word per row, horizontal only (no vertical words)
 - No scope/radar visualization
 - 2 free letter guesses at game start
+- Daily and weekly leaderboards
 """
 
-__version__ = "0.1.2"
-__all__ = ["models", "generator", "logic", "ui", "word_loader"]
+__version__ = "0.2.0"
+__all__ = ["models", "generator", "logic", "ui", "word_loader", "leaderboard", "leaderboard_page"]

wrdler/game_storage.py

@@ -12,7 +12,7 @@ Wrdler Specifications:
 - No word overlaps
 - 2 free letter guesses at game start
 """
-__version__ = "0.1.5"
+__version__ = "0.2.0"
 
 import json
 import tempfile
@@ -69,7 +69,8 @@ def serialize_game_settings(
     challenge_id: Optional[str] = None,
     game_title: Optional[str] = None,
     show_incorrect_guesses: bool = True,
-    enable_free_letters: bool = True
+    enable_free_letters: bool = True,
+    entry_type: str = "challenge"
 ) -> Dict[str, Any]:
     """
     Serialize game settings into a JSON-compatible dictionary.
@@ -96,6 +97,7 @@ def serialize_game_settings(
         game_title: Game title (e.g., "Wrdler Gradio AI")
         show_incorrect_guesses: Whether to show incorrect guesses
         enable_free_letters: Whether free letters feature is enabled
+        entry_type: Type of entry ("challenge", "daily", or "weekly")
 
     Returns:
         dict: Serialized game settings with users array
@@ -130,6 +132,7 @@ def serialize_game_settings(
 
     settings = {
         "challenge_id": challenge_id,
+        "entry_type": entry_type,
         "game_mode": game_mode,
         "grid_size": grid_size,
         "puzzle_options": {

wrdler/leaderboard.py

@@ -0,0 +1,758 @@
+# wrdler/leaderboard.py
+"""
+Wrdler Leaderboard System
+
+Manages daily and weekly leaderboards with automatic score submission,
+qualification checking, and historical lookup.
+
+Leaderboard Configuration:
+- Max display entries: 20 per leaderboard (can store more)
+- Daily reset: UTC midnight
+- Weekly reset: Monday UTC 00:00 (ISO week)
+- Sorting: score (desc), time (asc), difficulty (desc)
+- File format: Unified with challenge settings.json
+- Settings-based separation: Each unique settings combination gets its own leaderboard folder
+"""
+__version__ = "0.2.0"
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone, timedelta
+from typing import Dict, Any, List, Optional, Tuple, Literal
+import logging
+
+from wrdler.modules.storage import (
+    _get_json_from_repo,
+    _upload_json_to_repo
+)
+from wrdler.modules.constants import HF_REPO_ID, APP_SETTINGS
+from wrdler.game_storage import generate_uid
+
+logger = logging.getLogger(__name__)
+
+# Configuration
+MAX_DISPLAY_ENTRIES = 20
+DAILY_LEADERBOARD_PATH = "leaderboards/daily"
+WEEKLY_LEADERBOARD_PATH = "leaderboards/weekly"
+LEADERBOARD_INDEX_PATH = "leaderboards/index.json"
+
+# Entry types
+EntryType = Literal["daily", "weekly", "challenge"]
+
+
+@dataclass
+class GameSettings:
+    """Settings that define a unique leaderboard."""
+    game_mode: str = "classic"
+    wordlist_source: str = "classic.txt"
+    show_incorrect_guesses: bool = True
+    enable_free_letters: bool = True
+    puzzle_options: Dict[str, Any] = field(default_factory=lambda: {"spacer": 0, "may_overlap": False})
+
+    def matches(self, other: "GameSettings") -> bool:
+        """Check if two settings are equivalent (same leaderboard)."""
+        return (
+            self.game_mode == other.game_mode and
+            self.wordlist_source == other.wordlist_source and
+            self.show_incorrect_guesses == other.show_incorrect_guesses and
+            self.enable_free_letters == other.enable_free_letters and
+            self.puzzle_options.get("spacer", 0) == other.puzzle_options.get("spacer", 0) and
+            self.puzzle_options.get("may_overlap", False) == other.puzzle_options.get("may_overlap", False)
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "game_mode": self.game_mode,
+            "wordlist_source": self.wordlist_source,
+            "show_incorrect_guesses": self.show_incorrect_guesses,
+            "enable_free_letters": self.enable_free_letters,
+            "puzzle_options": self.puzzle_options,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "GameSettings":
+        """Create from dictionary."""
+        return cls(
+            game_mode=data.get("game_mode", "classic"),
+            wordlist_source=data.get("wordlist_source", "classic.txt"),
+            show_incorrect_guesses=data.get("show_incorrect_guesses", True),
+            enable_free_letters=data.get("enable_free_letters", True),
+            puzzle_options=data.get("puzzle_options", {"spacer": 0, "may_overlap": False}),
+        )
+
+    @classmethod
+    def from_leaderboard(cls, leaderboard: "LeaderboardSettings") -> "GameSettings":
+        """Extract settings from a leaderboard."""
+        return cls(
+            game_mode=leaderboard.game_mode,
+            wordlist_source=leaderboard.wordlist_source,
+            show_incorrect_guesses=leaderboard.show_incorrect_guesses,
+            enable_free_letters=leaderboard.enable_free_letters,
+            puzzle_options=leaderboard.puzzle_options,
+        )
+
+
+@dataclass
+class UserEntry:
+    """Single user entry in a leaderboard (matches challenge user format)."""
+    uid: str
+    username: str
+    word_list: List[str]
+    score: int
+    time: int  # seconds (matches existing 'time' field, not 'time_seconds')
+    timestamp: str
+    word_list_difficulty: Optional[float] = None
+    source_challenge_id: Optional[str] = None  # If entry came from a challenge
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "uid": self.uid,
+            "username": self.username,
+            "word_list": self.word_list,
+            "score": self.score,
+            "time": self.time,
+            "timestamp": self.timestamp,
+        }
+        if self.word_list_difficulty is not None:
+            result["word_list_difficulty"] = self.word_list_difficulty
+        if self.source_challenge_id is not None:
+            result["source_challenge_id"] = self.source_challenge_id
+        return result
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "UserEntry":
+        """Create from dictionary."""
+        return cls(
+            uid=data["uid"],
+            username=data["username"],
+            word_list=data["word_list"],
+            score=data["score"],
+            time=data.get("time", data.get("time_seconds", 0)),  # Handle both field names
+            timestamp=data["timestamp"],
+            word_list_difficulty=data.get("word_list_difficulty"),
+            source_challenge_id=data.get("source_challenge_id"),
+        )
+
+
+@dataclass
+class LeaderboardSettings:
+    """
+    Unified leaderboard/challenge settings format.
+    
+    This matches the existing challenge settings.json structure with added
+    entry_type field to distinguish between daily, weekly, and challenge entries.
+    The settings fields define what makes this leaderboard unique.
+    """
+    challenge_id: str  # Date-fileId for daily, week-fileId for weekly, UID for challenge
+    entry_type: EntryType  # "daily", "weekly", or "challenge"
+    game_mode: str = "classic"
+    grid_size: int = 8
+    puzzle_options: Dict[str, Any] = field(default_factory=lambda: {"spacer": 0, "may_overlap": False})
+    users: List[UserEntry] = field(default_factory=list)
+    created_at: str = ""
+    version: str = __version__
+    show_incorrect_guesses: bool = True
+    enable_free_letters: bool = True
+    wordlist_source: str = "classic.txt"
+    game_title: str = "Wrdler"
+    max_display_entries: int = MAX_DISPLAY_ENTRIES
+
+    def __post_init__(self):
+        if not self.created_at:
+            self.created_at = datetime.now(timezone.utc).isoformat()
+        if not self.game_title:
+            self.game_title = APP_SETTINGS.get("game_title", "Wrdler")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "challenge_id": self.challenge_id,
+            "entry_type": self.entry_type,
+            "game_mode": self.game_mode,
+            "grid_size": self.grid_size,
+            "puzzle_options": self.puzzle_options,
+            "users": [u.to_dict() for u in self.users],
+            "created_at": self.created_at,
+            "version": self.version,
+            "show_incorrect_guesses": self.show_incorrect_guesses,
+            "enable_free_letters": self.enable_free_letters,
+            "wordlist_source": self.wordlist_source,
+            "game_title": self.game_title,
+            "max_display_entries": self.max_display_entries,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "LeaderboardSettings":
+        """Create from dictionary."""
+        users = [UserEntry.from_dict(u) for u in data.get("users", [])]
+        return cls(
+            challenge_id=data["challenge_id"],
+            entry_type=data.get("entry_type", "challenge"),  # Default for legacy
+            game_mode=data.get("game_mode", "classic"),
+            grid_size=data.get("grid_size", 8),
+            puzzle_options=data.get("puzzle_options", {"spacer": 0, "may_overlap": False}),
+            users=users,
+            created_at=data.get("created_at", ""),
+            version=data.get("version", "0.1.0"),
+            show_incorrect_guesses=data.get("show_incorrect_guesses", True),
+            enable_free_letters=data.get("enable_free_letters", True),
+            wordlist_source=data.get("wordlist_source", "classic.txt"),
+            game_title=data.get("game_title", "Wrdler"),
+            max_display_entries=data.get("max_display_entries", MAX_DISPLAY_ENTRIES),
+        )
+
+    def get_display_users(self) -> List[UserEntry]:
+        """Get users limited to max_display_entries."""
+        return self.users[:self.max_display_entries]
+
+    def get_settings(self) -> GameSettings:
+        """Extract game settings from this leaderboard."""
+        return GameSettings.from_leaderboard(self)
+
+
+def get_current_daily_id() -> str:
+    """Get the date portion of the leaderboard ID for today (UTC)."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+def get_current_weekly_id() -> str:
+    """Get the week portion of the leaderboard ID for the current ISO week."""
+    now = datetime.now(timezone.utc)
+    iso_cal = now.isocalendar()
+    return f"{iso_cal.year}-W{iso_cal.week:02d}"
+
+
+def get_daily_leaderboard_path(date_id: str, file_id: int) -> str:
+    """Get the file path for a daily leaderboard (folder-based with settings.json)."""
+    return f"{DAILY_LEADERBOARD_PATH}/{date_id}-{file_id}/settings.json"
+
+
+def get_weekly_leaderboard_path(week_id: str, file_id: int) -> str:
+    """Get the file path for a weekly leaderboard (folder-based with settings.json)."""
+    return f"{WEEKLY_LEADERBOARD_PATH}/{week_id}-{file_id}/settings.json"
+
+
+def _sort_users(users: List[UserEntry]) -> List[UserEntry]:
+    """Sort users by score (desc), time (asc), difficulty (desc)."""
+    return sorted(
+        users,
+        key=lambda u: (
+            -u.score,
+            u.time,
+            -(u.word_list_difficulty or 0)
+        )
+    )
+
+
+def _load_index(repo_id: Optional[str] = None) -> Dict[str, Any]:
+    """Load the leaderboard index."""
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+    
+    data = _get_json_from_repo(repo_id, LEADERBOARD_INDEX_PATH, "dataset")
+    if not data:
+        return {"daily": {}, "weekly": {}}
+    return data
+
+
+def _save_index(index: Dict[str, Any], repo_id: Optional[str] = None) -> bool:
+    """Save the leaderboard index."""
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+    
+    return _upload_json_to_repo(index, repo_id, LEADERBOARD_INDEX_PATH, "dataset")
+
+
+def find_matching_leaderboard(
+    entry_type: EntryType,
+    period_id: str,
+    settings: GameSettings,
+    repo_id: Optional[str] = None
+) -> Tuple[Optional[int], Optional[LeaderboardSettings]]:
+    """
+    Find a leaderboard matching the given settings for a period.
+    
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date string or week identifier
+        settings: Game settings to match
+        repo_id: Repository ID
+    
+    Returns:
+        Tuple of (file_id, leaderboard) or (None, None) if not found
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+    
+    index = _load_index(repo_id)
+    period_entries = index.get(entry_type, {}).get(period_id, [])
+    
+    for entry in period_entries:
+        entry_settings = GameSettings.from_dict(entry)
+        if settings.matches(entry_settings):
+            file_id = entry["file_id"]
+            # Load the actual leaderboard
+            if entry_type == "daily":
+                path = get_daily_leaderboard_path(period_id, file_id)
+            else:
+                path = get_weekly_leaderboard_path(period_id, file_id)
+            
+            data = _get_json_from_repo(repo_id, path, "dataset")
+            if data:
+                return file_id, LeaderboardSettings.from_dict(data)
+    
+    return None, None
+
+
+def create_or_get_leaderboard(
+    entry_type: EntryType,
+    period_id: str,
+    settings: GameSettings,
+    repo_id: Optional[str] = None
+) -> Tuple[int, LeaderboardSettings]:
+    """
+    Get existing leaderboard or create a new one for the settings.
+    
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date string or week identifier
+        settings: Game settings
+        repo_id: Repository ID
+    
+    Returns:
+        Tuple of (file_id, leaderboard)
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+    
+    # Try to find existing
+    file_id, leaderboard = find_matching_leaderboard(entry_type, period_id, settings, repo_id)
+    
+    if leaderboard is not None:
+        return file_id, leaderboard
+    
+    # Create new leaderboard
+    index = _load_index(repo_id)
+    if entry_type not in index:
+        index[entry_type] = {}
+    if period_id not in index[entry_type]:
+        index[entry_type][period_id] = []
+    
+    # Get next file_id
+    existing_ids = [e["file_id"] for e in index[entry_type][period_id]]
+    file_id = max(existing_ids, default=-1) + 1
+    
+    # Create challenge_id (folder name)
+    challenge_id = f"{period_id}-{file_id}"
+    
+    # Create new leaderboard
+    leaderboard = LeaderboardSettings(
+        challenge_id=challenge_id,
+        entry_type=entry_type,
+        game_mode=settings.game_mode,
+        wordlist_source=settings.wordlist_source,
+        show_incorrect_guesses=settings.show_incorrect_guesses,
+        enable_free_letters=settings.enable_free_letters,
+        puzzle_options=settings.puzzle_options,
+        users=[]
+    )
+    
+    # Update index
+    index_entry = settings.to_dict()
+    index_entry["file_id"] = file_id
+    index[entry_type][period_id].append(index_entry)
+    _save_index(index, repo_id)
+    
+    return file_id, leaderboard
+
+
+def load_leaderboard(
+    entry_type: EntryType,
+    period_id: str,
+    file_id: int,
+    repo_id: Optional[str] = None
+) -> Optional[LeaderboardSettings]:
+    """
+    Load a specific leaderboard by file ID.
+
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date string or week identifier
+        file_id: File identifier
+        repo_id: Repository ID (uses HF_REPO_ID if None)
+
+    Returns:
+        LeaderboardSettings object or None if not found
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+
+    if entry_type == "daily":
+        path = get_daily_leaderboard_path(period_id, file_id)
+    elif entry_type == "weekly":
+        path = get_weekly_leaderboard_path(period_id, file_id)
+    else:
+        logger.error(f"Invalid entry_type for leaderboard: {entry_type}")
+        return None
+
+    logger.info(f"?? Loading leaderboard: {path}")
+    data = _get_json_from_repo(repo_id, path, "dataset")
+
+    if not data:
+        logger.info(f"?? No existing leaderboard found at {path}")
+        return None
+
+    return LeaderboardSettings.from_dict(data)
+
+
+def save_leaderboard(
+    leaderboard: LeaderboardSettings,
+    file_id: int,
+    repo_id: Optional[str] = None
+) -> bool:
+    """
+    Save a leaderboard to the repository.
+
+    Args:
+        leaderboard: LeaderboardSettings object to save
+        file_id: File identifier
+        repo_id: Repository ID (uses HF_REPO_ID if None)
+
+    Returns:
+        True if saved successfully, False otherwise
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+
+    # Extract period_id from challenge_id (format: "2025-01-27-0" or "2025-W04-0")
+    # The challenge_id is the folder name, which includes the file_id
+    parts = leaderboard.challenge_id.rsplit("-", 1)
+    if len(parts) == 2 and parts[1].isdigit():
+        period_id = parts[0]
+    else:
+        # Handle weekly format like "2025-W04-0"
+        parts = leaderboard.challenge_id.rsplit("-", 1)
+        period_id = parts[0] if len(parts) > 1 else leaderboard.challenge_id
+
+    if leaderboard.entry_type == "daily":
+        path = get_daily_leaderboard_path(period_id, file_id)
+    elif leaderboard.entry_type == "weekly":
+        path = get_weekly_leaderboard_path(period_id, file_id)
+    else:
+        logger.error(f"Cannot save leaderboard with entry_type: {leaderboard.entry_type}")
+        return False
+
+    logger.info(f"?? Saving leaderboard: {path}")
+    return _upload_json_to_repo(leaderboard.to_dict(), repo_id, path, "dataset")
+
+
+def create_user_entry(
+    username: str,
+    score: int,
+    time_seconds: int,
+    word_list: List[str],
+    word_list_difficulty: Optional[float] = None,
+    source_challenge_id: Optional[str] = None
+) -> UserEntry:
+    """Create a new user entry."""
+    return UserEntry(
+        uid=generate_uid(),
+        username=username,
+        word_list=word_list,
+        score=score,
+        time=time_seconds,
+        word_list_difficulty=word_list_difficulty,
+        source_challenge_id=source_challenge_id,
+        timestamp=datetime.now(timezone.utc).isoformat()
+    )
+
+
+def check_qualification(
+    leaderboard: Optional[LeaderboardSettings],
+    score: int,
+    time_seconds: int,
+    word_list_difficulty: Optional[float] = None
+) -> bool:
+    """
+    Check if a score qualifies for the leaderboard display (top 20).
+
+    Note: The leaderboard can store more than 20 entries, but only top 20 are displayed.
+    This function checks if the score would be in the top 20.
+
+    Args:
+        leaderboard: Existing leaderboard (or None if new)
+        score: Score to check
+        time_seconds: Time to complete
+        word_list_difficulty: Difficulty score
+
+    Returns:
+        True if qualifies for display, False otherwise
+    """
+    if leaderboard is None or len(leaderboard.users) < MAX_DISPLAY_ENTRIES:
+        return True
+
+    # Get the 20th entry (last displayed)
+    display_users = leaderboard.get_display_users()
+    if len(display_users) < MAX_DISPLAY_ENTRIES:
+        return True
+
+    lowest = display_users[-1]
+
+    # Primary: higher score qualifies
+    if score > lowest.score:
+        return True
+    if score < lowest.score:
+        return False
+
+    # Secondary: faster time qualifies (for equal score)
+    if time_seconds < lowest.time:
+        return True
+    if time_seconds > lowest.time:
+        return False
+
+    # Tertiary: higher difficulty qualifies (for equal score and time)
+    entry_diff = word_list_difficulty or 0
+    lowest_diff = lowest.word_list_difficulty or 0
+    return entry_diff > lowest_diff
+
+
+def submit_to_leaderboard(
+    entry_type: EntryType,
+    period_id: str,
+    user_entry: UserEntry,
+    settings: GameSettings,
+    repo_id: Optional[str] = None
+) -> Tuple[bool, Optional[int]]:
+    """
+    Submit a user entry to a leaderboard if it qualifies.
+
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date or week identifier
+        user_entry: UserEntry to submit
+        settings: Game settings to match leaderboard
+        repo_id: Repository ID
+
+    Returns:
+        Tuple of (success, rank) where rank is 1-indexed position or None if didn't qualify
+    """
+    if repo_id is None:
+        repo_id = HF_REPO_ID
+
+    # Get or create matching leaderboard
+    file_id, leaderboard = create_or_get_leaderboard(entry_type, period_id, settings, repo_id)
+
+    # Check qualification for display
+    qualifies = check_qualification(
+        leaderboard,
+        user_entry.score,
+        user_entry.time,
+        user_entry.word_list_difficulty
+    )
+
+    if not qualifies:
+        logger.info(f"? Score {user_entry.score} did not qualify for top {MAX_DISPLAY_ENTRIES} in {period_id}")
+        return False, None
+
+    # Add entry and sort
+    leaderboard.users.append(user_entry)
+    leaderboard.users = _sort_users(leaderboard.users)
+
+    # Find rank (1-indexed) - check if in display range
+    rank = None
+    for i, u in enumerate(leaderboard.users[:MAX_DISPLAY_ENTRIES]):
+        if u.uid == user_entry.uid:
+            rank = i + 1
+            break
+
+    if rank is None:
+        # Entry was sorted out of top 20
+        logger.info(f"? Score {user_entry.score} was sorted out of top {MAX_DISPLAY_ENTRIES}")
+        # Still save the entry (stored but not displayed)
+        save_leaderboard(leaderboard, file_id, repo_id)
+        return False, None
+
+    # Save leaderboard
+    if save_leaderboard(leaderboard, file_id, repo_id):
+        logger.info(f"? Added to {entry_type} leaderboard at rank {rank}")
+        return True, rank
+    else:
+        logger.error(f"? Failed to save leaderboard {period_id}")
+        return False, None
+
+
+def submit_score_to_all_leaderboards(
+    username: str,
+    score: int,
+    time_seconds: int,
+    word_list: List[str],
+    settings: GameSettings,
+    word_list_difficulty: Optional[float] = None,
+    source_challenge_id: Optional[str] = None,
+    repo_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Submit a score to both daily and weekly leaderboards matching the settings.
+
+    This is the main entry point for game completions.
+
+    Args:
+        username: Player name
+        score: Final score
+        time_seconds: Time to complete
+        word_list: Words played
+        settings: Game settings (determines which leaderboard)
+        word_list_difficulty: Difficulty score
+        source_challenge_id: If from a challenge, the original challenge_id
+        repo_id: Repository ID
+
+    Returns:
+        Dict with results:
+        {
+            "daily": {"qualified": bool, "rank": int|None, "id": str},
+            "weekly": {"qualified": bool, "rank": int|None, "id": str},
+            "entry_uid": str,
+            "settings": {...}
+        }
+    """
+    logger.info(f"?? Submitting score: {score} by {username} with settings: {settings.game_mode}")
+
+    # Get current period IDs
+    daily_id = get_current_daily_id()
+    weekly_id = get_current_weekly_id()
+
+    # Create user entry for daily
+    daily_entry = create_user_entry(
+        username=username,
+        score=score,
+        time_seconds=time_seconds,
+        word_list=word_list,
+        word_list_difficulty=word_list_difficulty,
+        source_challenge_id=source_challenge_id
+    )
+
+    # Submit to daily
+    daily_qualified, daily_rank = submit_to_leaderboard(
+        "daily", daily_id, daily_entry, settings, repo_id
+    )
+
+    # Create separate user entry for weekly (different UID)
+    weekly_entry = create_user_entry(
+        username=username,
+        score=score,
+        time_seconds=time_seconds,
+        word_list=word_list,
+        word_list_difficulty=word_list_difficulty,
+        source_challenge_id=source_challenge_id
+    )
+
+    # Submit to weekly
+    weekly_qualified, weekly_rank = submit_to_leaderboard(
+        "weekly", weekly_id, weekly_entry, settings, repo_id
+    )
+
+    results = {
+        "daily": {"qualified": daily_qualified, "rank": daily_rank, "id": daily_id},
+        "weekly": {"qualified": weekly_qualified, "rank": weekly_rank, "id": weekly_id},
+        "entry_uid": daily_entry.uid,
+        "settings": settings.to_dict()
+    }
+
+    logger.info(f"?? Leaderboard results: {results}")
+    return results
+
+
+def get_leaderboards_for_settings(
+    entry_type: EntryType,
+    period_id: str,
+    settings: GameSettings,
+    repo_id: Optional[str] = None
+) -> Optional[LeaderboardSettings]:
+    """
+    Get leaderboard matching specific settings for a period.
+    
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date or week identifier
+        settings: Game settings to match
+        repo_id: Repository ID
+    
+    Returns:
+        LeaderboardSettings or None if not found
+    """
+    _, leaderboard = find_matching_leaderboard(entry_type, period_id, settings, repo_id)
+    return leaderboard
+
+
+def get_last_n_daily_leaderboards(
+    n: int = 7,
+    settings: Optional[GameSettings] = None,
+    repo_id: Optional[str] = None
+) -> List[Tuple[str, Optional[LeaderboardSettings]]]:
+    """
+    Get the last N days of daily leaderboards for specific settings.
+
+    Args:
+        n: Number of days to retrieve
+        settings: Game settings to filter by (None = default settings)
+        repo_id: Repository ID
+
+    Returns:
+        List of tuples (date_id, leaderboard) in reverse chronological order
+    """
+    if settings is None:
+        settings = GameSettings()
+    
+    results = []
+    today = datetime.now(timezone.utc).date()
+
+    for i in range(n):
+        date = today - timedelta(days=i)
+        date_id = date.strftime("%Y-%m-%d")
+        leaderboard = get_leaderboards_for_settings("daily", date_id, settings, repo_id)
+        results.append((date_id, leaderboard))
+
+    return results
+
+
+def list_available_periods(
+    entry_type: EntryType,
+    limit: int = 30,
+    repo_id: Optional[str] = None
+) -> List[str]:
+    """
+    List available period IDs from the index.
+
+    Args:
+        entry_type: "daily" or "weekly"
+        limit: Maximum number of IDs to return
+        repo_id: Repository ID
+
+    Returns:
+        List of period IDs in reverse chronological order
+    """
+    index = _load_index(repo_id)
+    periods = list(index.get(entry_type, {}).keys())
+    periods.sort(reverse=True)
+    return periods[:limit]
+
+
+def list_settings_for_period(
+    entry_type: EntryType,
+    period_id: str,
+    repo_id: Optional[str] = None
+) -> List[Dict[str, Any]]:
+    """
+    List all settings combinations available for a period.
+    
+    Args:
+        entry_type: "daily" or "weekly"
+        period_id: Date or week identifier
+        repo_id: Repository ID
+    
+    Returns:
+        List of settings dictionaries with file_id
+    """
+    index = _load_index(repo_id)
+    return index.get(entry_type, {}).get(period_id, [])

wrdler/leaderboard_page.py

@@ -0,0 +1,225 @@
+# wrdler/leaderboard_page.py
+"""
+Wrdler Leaderboard Page
+
+Streamlit page component for displaying daily and weekly leaderboards
+with historical lookup capabilities.
+"""
+__version__ = "0.2.0"
+
+import streamlit as st
+from datetime import datetime
+from typing import Optional
+
+from wrdler.leaderboard import (
+    load_leaderboard,
+    get_last_n_daily_leaderboards,
+    get_current_daily_id,
+    get_current_weekly_id,
+    list_available_leaderboards,
+    LeaderboardSettings,
+    MAX_DISPLAY_ENTRIES
+)
+from wrdler.modules.constants import APP_SETTINGS
+
+
+def _format_time(seconds: int) -> str:
+    """Format seconds as MM:SS."""
+    mins, secs = divmod(seconds, 60)
+    return f"{mins:02d}:{secs:02d}"
+
+
+def _get_rank_emoji(rank: int) -> str:
+    """Get emoji for rank."""
+    if rank == 1:
+        return "??"
+    elif rank == 2:
+        return "??"
+    elif rank == 3:
+        return "??"
+    return f"{rank}."
+
+
+def _render_leaderboard_table(leaderboard: Optional[LeaderboardSettings], title: str):
+    """Render a leaderboard as a styled table."""
+    if title:
+        st.subheader(title)
+
+    if leaderboard is None or not leaderboard.users:
+        st.info("No entries yet. Be the first to set a high score!")
+        return
+
+    # Get display users (limited to max_display_entries)
+    display_users = leaderboard.get_display_users()
+
+    # Build table HTML
+    rows = []
+    for i, user in enumerate(display_users, 1):
+        rank_display = _get_rank_emoji(i)
+        time_display = _format_time(user.time)
+        difficulty = f"{user.word_list_difficulty:.2f}" if user.word_list_difficulty else "-"
+
+        # Show challenge indicator if from a challenge
+        challenge_badge = " ??" if user.source_challenge_id else ""
+
+        rows.append(f"""
+        <tr>
+            <td style="text-align:center;font-size:1.2rem;">{rank_display}</td>
+            <td><strong>{user.username}</strong>{challenge_badge}</td>
+            <td style="text-align:center;color:#20d46c;font-weight:bold;">{user.score}</td>
+            <td style="text-align:center;">{time_display}</td>
+            <td style="text-align:center;">{difficulty}</td>
+        </tr>
+        """)
+
+    table_html = f"""
+    <style>
+        .lb-table {{
+            width: 100%;
+            border-collapse: collapse;
+            background: rgba(29, 100, 200, 0.2);
+            border-radius: 0.5rem;
+            overflow: hidden;
+        }}
+        .lb-table th {{
+            background: #1d64c8;
+            color: white;
+            padding: 0.75rem;
+            text-align: center;
+        }}
+        .lb-table td {{
+            padding: 0.5rem 0.75rem;
+            border-bottom: 1px solid rgba(255,255,255,0.1);
+            color: white;
+        }}
+        .lb-table tr:hover {{
+            background: rgba(29, 100, 200, 0.3);
+        }}
+    </style>
+    <table class="lb-table">
+        <thead>
+            <tr>
+                <th>Rank</th>
+                <th>Player</th>
+                <th>Score</th>
+                <th>Time</th>
+                <th>Difficulty</th>
+            </tr>
+        </thead>
+        <tbody>
+            {''.join(rows)}
+        </tbody>
+    </table>
+    """
+
+    st.markdown(table_html, unsafe_allow_html=True)
+
+    # Show entry count and last updated
+    total_entries = len(leaderboard.users)
+    if total_entries > MAX_DISPLAY_ENTRIES:
+        st.caption(f"Showing top {MAX_DISPLAY_ENTRIES} of {total_entries} entries � Last updated: {leaderboard.created_at}")
+    else:
+        st.caption(f"{total_entries} entries � Last updated: {leaderboard.created_at}")
+
+
+def render_leaderboard_page():
+    """Render the full leaderboard page."""
+    game_title = APP_SETTINGS.get("game_title", "Wrdler")
+    st.title(f"?? {game_title} Leaderboards")
+
+    # Tab selection
+    tab1, tab2, tab3 = st.tabs(["?? Daily", "?? Weekly", "?? History"])
+
+    with tab1:
+        _render_daily_tab()
+
+    with tab2:
+        _render_weekly_tab()
+
+    with tab3:
+        _render_history_tab()
+
+
+def _render_daily_tab():
+    """Render daily leaderboards tab."""
+    st.header("?? Daily Leaderboards")
+    st.write(f"Top {MAX_DISPLAY_ENTRIES} scores for each day. Resets at UTC midnight.")
+
+    # Get last 7 days
+    daily_boards = get_last_n_daily_leaderboards(7)
+
+    for date_id, leaderboard in daily_boards:
+        # Format date nicely
+        try:
+            date_obj = datetime.strptime(date_id, "%Y-%m-%d")
+            if date_id == get_current_daily_id():
+                title = f"?? Today ({date_obj.strftime('%B %d, %Y')})"
+            else:
+                title = date_obj.strftime("%A, %B %d, %Y")
+        except ValueError:
+            title = date_id
+
+        with st.expander(title, expanded=(date_id == get_current_daily_id())):
+            _render_leaderboard_table(leaderboard, "")
+
+
+def _render_weekly_tab():
+    """Render weekly leaderboard tab."""
+    st.header("?? Weekly Leaderboard")
+    st.write(f"Top {MAX_DISPLAY_ENTRIES} scores for the current week. Resets Monday at UTC midnight.")
+
+    weekly_id = get_current_weekly_id()
+    leaderboard = load_leaderboard("weekly", weekly_id)
+
+    # Parse week for display
+    try:
+        year, week = weekly_id.split("-W")
+        title = f"Week {int(week)}, {year}"
+    except ValueError:
+        title = weekly_id
+
+    _render_leaderboard_table(leaderboard, f"?? {title}")
+
+
+def _render_history_tab():
+    """Render historical leaderboards tab."""
+    st.header("?? Historical Leaderboards")
+    st.write("Look up past leaderboards.")
+
+    col1, col2 = st.columns(2)
+
+    with col1:
+        st.subheader("Daily History")
+        daily_ids = list_available_leaderboards("daily", limit=30)
+        selected_daily = st.selectbox(
+            "Select a date",
+            options=daily_ids,
+            key="history_daily_select"
+        )
+
+        if st.button("Load Daily", key="load_daily"):
+            leaderboard = load_leaderboard("daily", selected_daily)
+            _render_leaderboard_table(leaderboard, f"Daily: {selected_daily}")
+
+    with col2:
+        st.subheader("Weekly History")
+        weekly_ids = list_available_leaderboards("weekly", limit=20)
+        selected_weekly = st.selectbox(
+            "Select a week",
+            options=weekly_ids,
+            key="history_weekly_select"
+        )
+
+        if st.button("Load Weekly", key="load_weekly"):
+            leaderboard = load_leaderboard("weekly", selected_weekly)
+            _render_leaderboard_table(leaderboard, f"Weekly: {selected_weekly}")
+
+
+# Entry point for standalone testing
+if __name__ == "__main__":
+    st.set_page_config(
+        page_title="Wrdler Leaderboards",
+        page_icon="??",
+        layout="wide"
+    )
+    render_leaderboard_page()

wrdler/modules/constants.py

@@ -1,12 +1,14 @@
-# battlewords/modules/constants.py
+# wrdler/modules/constants.py
 """
 Storage-related constants for BattleWords.
 Trimmed version of OpenBadge constants - only includes what's needed for storage.py
 """
 import os
+import json
 import tempfile
 import logging
 from pathlib import Path
+from typing import Dict, Any
 from dotenv import load_dotenv
 
 # Load environment variables from .env file
@@ -22,7 +24,7 @@ HF_REPO_ID = os.getenv("HF_REPO_ID", "Surn/Storage")
 SPACE_NAME = os.getenv('SPACE_NAME', 'Surn/Wrdler')
 SHORTENER_JSON_FILE = "shortener.json"
 USE_HF_WORDS = os.getenv("USE_HF_WORDS", "false").lower() == "true"
-HF_WORD_LIST_REPO_ID= os.getenv("HF_WORD_LIST_REPO_ID", "ysharma/Chat_with_Meta_llama3_1_8b")
+HF_WORD_LIST_REPO_ID = os.getenv("HF_WORD_LIST_REPO_ID", "ysharma/Chat_with_Meta_llama3_1_8b")
 
 # List of smaller, faster fallback models if the primary one fails
 AI_MODELS = [
@@ -34,7 +36,72 @@ AI_MODELS = [
     "NousResearch/Hermes-2-Pro-Llama-3-8B"    
 ]
 
+
+# ---------------------------------------------------------------------------
+# Application Settings
+# ---------------------------------------------------------------------------
+
+def load_settings() -> Dict[str, Any]:
+    """
+    Load settings from settings.json file.
+    
+    Looks for settings.json in the project root directory.
+    Returns merged defaults with any overrides from the file.
+    Environment variables can override specific settings (e.g., GAME_TITLE).
+    
+    Returns:
+        Dict containing all application settings
+    """
+    # Path to settings.json in project root
+    settings_path = Path(__file__).parent.parent.parent / "settings.json"
+    
+    default_settings = {
+        # Game identity
+        "game_title": os.getenv("GAME_TITLE", "Wrdler"),
+        
+        # Display settings
+        "show_incorrect_guesses": True,
+        "enable_free_letters": False,
+        "show_challenge_links": True,
+        
+        # Audio settings
+        "sound_effects_enabled": True,
+        "sound_effects_volume": 10,
+        "music_enabled": False,
+        "music_volume": 10,
+        
+        # Game defaults
+        "default_wordlist": "classic.txt",
+        "default_game_mode": "classic",
+        
+        # Grid configuration (Wrdler: 8x6)
+        "grid_rows": 6,
+        "grid_cols": 8,
+        "words_per_puzzle": 6,
+        "free_letters_count": 2,
+        "max_incorrect_guesses": 10,
+    }
+
+    try:
+        if settings_path.exists():
+            with open(settings_path, "r", encoding="utf-8") as f:
+                loaded = json.load(f)
+                # Merge with defaults (loaded settings override defaults)
+                return {**default_settings, **loaded}
+    except Exception:
+        pass
+
+    return default_settings
+
+
+# Load settings at module level for easy import
+APP_SETTINGS = load_settings()
+
+
+# ---------------------------------------------------------------------------
 # Temporary Directory Configuration
+# ---------------------------------------------------------------------------
+
 try:
     if os.environ.get('TMPDIR'):
         TMPDIR = os.environ['TMPDIR']

wrdler/ui.py

@@ -28,6 +28,8 @@ from .audio import (
     play_sound_effect,
 )
 from .game_storage import load_game_from_sid, save_game_to_hf, get_shareable_url, add_user_result_to_game
+from .modules.constants import APP_SETTINGS
+from .leaderboard import submit_score_to_all_leaderboards
 
 st.set_page_config(initial_sidebar_state="collapsed")
 
@@ -160,6 +162,49 @@ window.addEventListener('appinstalled', () => {
 
 CoordLike = Tuple[int, int]
 
+def _get_effective_game_title() -> str:
+    """
+    Get the effective game title, prioritizing:
+    1. Challenge-specific game_title from shared_game_settings
+    2. Session state game_title (if set)
+    3. APP_SETTINGS default
+    4. Fallback to "Wrdler"
+    """
+    # First check shared game settings (challenge mode)
+    shared_settings = st.session_state.get("shared_game_settings")
+    if shared_settings and shared_settings.get("game_title"):
+        return shared_settings["game_title"]
+    
+    # Then check session state
+    if st.session_state.get("game_title"):
+        return st.session_state["game_title"]
+    
+    # Fall back to APP_SETTINGS
+    return APP_SETTINGS.get("game_title", "Wrdler")
+
+
+def _apply_challenge_settings(settings: dict) -> None:
+    """
+    Apply challenge-specific settings from loaded shared game to session state.
+    This ensures the UI respects settings like show_incorrect_guesses, 
+    enable_free_letters, and game_title from the challenge creator.
+    
+    Args:
+        settings: Dictionary of settings from load_game_from_sid()
+    """
+    # Apply show_incorrect_guesses if present in challenge
+    if "show_incorrect_guesses" in settings:
+        st.session_state.show_incorrect_guesses = settings["show_incorrect_guesses"]
+    
+    # Apply enable_free_letters if present in challenge
+    if "enable_free_letters" in settings:
+        st.session_state.enable_free_letters = settings["enable_free_letters"]
+    
+    # Store game_title in session state if present
+    if "game_title" in settings:
+        st.session_state.game_title = settings["game_title"]
+
+
 def fig_to_pil_rgba(fig):
     canvas = FigureCanvas(fig)
     canvas.draw()
@@ -499,11 +544,18 @@ border-radius: 50% !important;
             position:relative;
             z-index: 1200;
             }
+          .username_input id[="text_input"] { color: #fff;}
           .st-emotion-cache-18kf3ut, .stColumn.st-emotion-cache-116javk {padding-bottom:3px;}
 
           /* grid adjustments */
+          # @media (max-width: 705px){
+          #   .bw-cell {
+          #       min-height: 2.5rem;
+          #       min-width: 1.75rem;
+          #   }
+          # }
           @media (min-width: 560px){
-           div[data-testid="stButton"] button { max-width: 100%; aspect-ratio: 16 / 11; min-height: 1.75rem; display: flex;;}           
+           div[data-testid="stButton"] button { max-width: 100%; aspect-ratio: 16 / 11; min-height: 1.75rem; display: flex;}           
            .st-key-new_game_btn > div[data-testid="stButton"] button, .st-key-sort_wordlist_btn > div[data-testid="stButton"] button { min-height: calc(100% + 20px) !important;}
            .st-emotion-cache-ckafi0 { gap:0.1rem !important; min-height: calc(100% + 20px) !important; aspect-ratio: 16 / 11; width: auto !important;  flex: 1 1 auto !important;  min-width: 100% !important;  max-width: 100% !important;}
            /*.st-emotion-cache-1n6tfoc { aspect-ratio: 16 / 11; min-height: calc(100% + 20px) !important;}*/
@@ -513,9 +565,8 @@ border-radius: 50% !important;
                 position:relative;
                 z-index: 1200;
               }
-            
-
           }
+
           div[data-testid="stElementToolbarButtonContainer"], button[data-testid="stBaseButton-elementToolbar"], button[data-testid="stBaseButton-elementToolbar"]:hover {
                display: none;
           }
@@ -604,6 +655,11 @@ def _init_session() -> None:
     # Check if we're loading a shared game
     shared_settings = st.session_state.get("shared_game_settings")
 
+    # Apply challenge-specific settings before initializing defaults
+    # This ensures show_incorrect_guesses, enable_free_letters, game_title are set from challenge
+    if shared_settings:
+        _apply_challenge_settings(shared_settings)
+
     # Ensure a default selection exists before creating the puzzle
     files = get_wordlist_files()
     if "selected_wordlist" not in st.session_state and files:
@@ -736,6 +792,13 @@ def _new_game() -> None:
     st.session_state.incorrect_guesses = []
     st.session_state.free_letters = set()
     st.session_state.free_letters_used = 0
+    
+    # Reset share/leaderboard state for new game
+    st.session_state.pop("share_url", None)
+    st.session_state.pop("share_sid", None)
+    st.session_state.pop("leaderboard_submitted", None)
+    st.session_state.pop("leaderboard_results", None)
+    st.session_state.pop("hide_gameover_overlay", None)
 
     # Preserve preferences - but do NOT set widget-bound keys like game_mode
     # game_mode is managed by the selectbox widget in _render_sidebar()
@@ -776,7 +839,9 @@ def _sync_back(state: GameState) -> None:
 
 
 def _render_header():
-    st.title(f"Wrdler v{version}")
+    # Use dynamic game title (from challenge settings or APP_SETTINGS)
+    game_title = _get_effective_game_title()
+    st.title(f"{game_title} v{version}")
 
     # Update subtitle based on free letters setting
     if st.session_state.get("enable_free_letters", False):
@@ -1740,7 +1805,7 @@ def _game_over_content(state: GameState) -> None:
               /*filter: invert(1);*/
            }
            .st-bb {background-color: rgba(29, 100, 200, 0.5);} 
-           .st-key-generate_share_link div[data-testid="stButton"] button { aspect-ratio: auto;} 
+           .st-key-generate_share_link div[data-testid="stButton"] button, .st-key-submit_leaderboard_only div[data-testid="stButton"] button { aspect-ratio: auto;} 
            .st-key-generate_share_link div[data-testid="stButton"] button:hover { color: #1d64c8;}
         </style>
         """,
@@ -1845,6 +1910,33 @@ def _game_over_content(state: GameState) -> None:
         else:
             username = "Anonymous"
 
+        # Helper function to submit to leaderboards
+        def _submit_to_leaderboards(username: str, score: int, time_secs: int, word_list: list, challenge_id: str = None):
+            """Submit score to daily and weekly leaderboards."""
+            from .leaderboard import GameSettings, submit_score_to_all_leaderboards
+            
+            settings = GameSettings(
+                game_mode=state.game_mode,
+                wordlist_source=st.session_state.get("selected_wordlist", "classic.txt"),
+                show_incorrect_guesses=st.session_state.get("show_incorrect_guesses", True),
+                enable_free_letters=st.session_state.get("enable_free_letters", False),
+                puzzle_options={
+                    "spacer": getattr(state.puzzle, "spacer", 1),
+                    "may_overlap": getattr(state.puzzle, "may_overlap", False)
+                }
+            )
+            
+            results = submit_score_to_all_leaderboards(
+                username=username,
+                score=score,
+                time_seconds=time_secs,
+                word_list=word_list,
+                settings=settings,
+                word_list_difficulty=difficulty_value,
+                source_challenge_id=challenge_id
+            )
+            return results
+
         # Check if share URL already generated
         if "share_url" not in st.session_state or st.session_state.get("share_url") is None:
             button_text = "📊 Submit Your Result" if is_shared_game else "🔗 Generate Share Link"
@@ -1872,6 +1964,17 @@ def _game_over_content(state: GameState) -> None:
                             st.session_state["share_url"] = share_url
                             st.session_state["share_sid"] = existing_sid
                             st.session_state["show_challenge_share_links"] = True
+                            
+                            # Also submit to daily/weekly leaderboards
+                            try:
+                                lb_results = _submit_to_leaderboards(
+                                    username, state.score, elapsed_seconds, word_list, existing_sid
+                                )
+                                st.session_state["leaderboard_submitted"] = True
+                                st.session_state["leaderboard_results"] = lb_results
+                            except Exception as lb_err:
+                                st.warning(f"Challenge submitted but leaderboard update failed: {lb_err}")
+                            
                             st.success(f"✅ Result submitted for {username}!")
                             st.rerun()
                         else:
@@ -1886,7 +1989,7 @@ def _game_over_content(state: GameState) -> None:
                             score=state.score,
                             time_seconds=elapsed_seconds,
                             game_mode=state.game_mode,
-                            grid_size=6, # Wrdler:6 rows (8 columns)
+                            grid_size=6,  # Wrdler: 6 rows (8 columns)
                             spacer=spacer,
                             may_overlap=may_overlap,
                             wordlist_source=wordlist_source
@@ -1896,13 +1999,54 @@ def _game_over_content(state: GameState) -> None:
                             share_url = get_shareable_url(sid)
                             st.session_state["share_url"] = share_url
                             st.session_state["share_sid"] = sid
-                            st.session_state["show_challenge_share_links"] = True 
+                            st.session_state["show_challenge_share_links"] = True
+                            
+                            # Also submit to daily/weekly leaderboards
+                            try:
+                                lb_results = _submit_to_leaderboards(
+                                    username, state.score, elapsed_seconds, word_list, sid
+                                )
+                                st.session_state["leaderboard_submitted"] = True
+                                st.session_state["leaderboard_results"] = lb_results
+                            except Exception as lb_err:
+                                st.warning(f"Challenge created but leaderboard update failed: {lb_err}")
+                            
                             st.rerun()
                         else:
                             st.error("Failed to generate short URL")
-                    
+
                 except Exception as e:
-                    st.error(f"Failed to save game: {e}")                
+                    st.error(f"Failed to save game: {e}")
+            
+            # Show separate "Submit to Leaderboard" button when NOT in a challenge
+            if not is_shared_game and not st.session_state.get("leaderboard_submitted", False):
+                st.markdown("---")
+                st.markdown("##### 🏆 Or just submit to leaderboards")
+                if st.button("🏆 Submit to Leaderboards", key="submit_leaderboard_only", use_container_width=True):
+                    try:
+                        word_list = [w.text for w in state.puzzle.words]
+                        lb_results = _submit_to_leaderboards(
+                            username, state.score, elapsed_seconds, word_list
+                        )
+                        st.session_state["leaderboard_submitted"] = True
+                        st.session_state["leaderboard_results"] = lb_results
+                        
+                        # Show results
+                        daily_info = lb_results.get("daily", {})
+                        weekly_info = lb_results.get("weekly", {})
+                        
+                        if daily_info.get("qualified") or weekly_info.get("qualified"):
+                            msg_parts = []
+                            if daily_info.get("qualified"):
+                                msg_parts.append(f"Daily #{daily_info['rank']}")
+                            if weekly_info.get("qualified"):
+                                msg_parts.append(f"Weekly #{weekly_info['rank']}")
+                            st.success(f"✅ Submitted! Ranked: {', '.join(msg_parts)}")
+                        else:
+                            st.info("✅ Score submitted (not in top 20)")
+                        st.rerun()
+                    except Exception as e:
+                        st.error(f"Failed to submit to leaderboards: {e}")
         else:
             # Conditionally display the generated share URL
             if st.session_state.get("show_challenge_share_links", False):
@@ -1929,9 +2073,9 @@ def _game_over_content(state: GameState) -> None:
                         margin-top:6px;
                         justify-content:center;
                     ">
-                    
+
                     <strong><a href="{_share_url_attr}"
-                        target="_blank" 
+                        target="_blank"
                         rel="noopener noreferrer"
                         style="text-decoration: underline; color: #fff; word-break: break-all; filter: drop-shadow(1px 1px 2px #003);">
                     {_share_url_text}
@@ -1941,17 +2085,35 @@ def _game_over_content(state: GameState) -> None:
                     height=80
                 )
             else:
-                # Do not display the share URL, but confirm it’s saved/submitted
+                # Do not display the share URL, but confirm it's saved/submitted
                 st.success("✅ Your result has been saved.")
+        
+        # Show leaderboard submission status if already submitted
+        if st.session_state.get("leaderboard_submitted", False):
+            lb_results = st.session_state.get("leaderboard_results", {})
+            daily_info = lb_results.get("daily", {})
+            weekly_info = lb_results.get("weekly", {})
+            
+            status_parts = []
+            if daily_info.get("qualified"):
+                status_parts.append(f"Daily #{daily_info['rank']}")
+            if weekly_info.get("qualified"):
+                status_parts.append(f"Weekly #{weekly_info['rank']}")
+            
+            if status_parts:
+                st.info(f"🏆 Leaderboard: {', '.join(status_parts)}")
+            else:
+                st.info("🏆 Submitted to leaderboards")
 
     st.markdown("---")
 
     # Dialog actions
     if st.button("Close", key="close_game_over"):
-        st.session_state["hide_gameover_overlay"] = True  # Changed from show_gameover_overlay = False
+        st.session_state["hide_gameover_overlay"] = True
         st.session_state["remount_background_audio"] = True
         st.rerun()
 
+
 # Prefer st.dialog/experimental_dialog; fallback to st.modal if unavailable
 _Dialog = getattr(st, "dialog", getattr(st, "experimental_dialog", None))
 if _Dialog:
@@ -2029,6 +2191,9 @@ def run_app():
                 st.session_state["loaded_game_sid"] = sid  # Store sid for adding results later
                 st.session_state["shared_game_loaded"] = True
 
+                # Apply challenge-specific settings (show_incorrect_guesses, enable_free_letters, game_title)
+                _apply_challenge_settings(settings)
+
                 # Get best score and time from users array
                 users = settings.get("users", [])
                 if users:
@@ -2097,7 +2262,7 @@ def _on_game_option_change() -> None:
             # st.query_params may be a Mapping; pop safely if supported
             try:
                 if "game_id" in qp:
-                    qp.pop("game_id")                
+                    qp.pop("game_id")
             except Exception:
                 # Fallback: clear all params if pop not supported
                 try:
@@ -2107,7 +2272,6 @@ def _on_game_option_change() -> None:
     except Exception:
         pass
 
-
     # Clear challenge session flags and links
     if st.session_state.get("loaded_game_sid") is not None:
         st.session_state.loaded_game_sid = None