v0.2.5

Increase leaderboard display limit to top 25 entries

Updated leaderboard system to display the top 25 entries instead of the top 20. Introduced `MAX_DISPLAY_ENTRIES` environment variable for configurable display limits, defaulting to 25. Adjusted qualification logic, sorting, and rendering to reflect the new limit.

Made username input mandatory for leaderboard submissions, replacing "Anonymous" with "Your Name" as the placeholder. Added validation to prevent submissions without a valid username. Updated privacy policy to require usernames while avoiding PII storage.

Improved leaderboard rendering with dynamic table height calculation. Limited historical weekly periods displayed to 6. Updated documentation, constants, and storage structure to align with the new configuration. Incremented version numbers to reflect changes.

.gitignore

@@ -491,3 +491,4 @@ secrets.*
 /package.json
 /package-lock.json
 /.claude
+/.github

CLAUDE.md

@@ -57,7 +57,7 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords:
 ### Daily & Weekly Leaderboards
 - **Settings-Based Separation:** Each unique settings combo creates separate leaderboard
   - Settings: `game_mode`, `wordlist_source`, `show_incorrect_guesses`, `enable_free_letters`, `puzzle_options` (spacer, may_overlap)
-- **Auto Score Submission:** Checks qualification for top 20 after game completion
+- **Auto Score Submission:** Checks qualification for top 25 after game completion
 - **Storage:** Folder-based discovery at `games/leaderboards/{daily|weekly}/{period}/{file_id}/settings.json`
 - **File ID Format:** `{wordlist_source}-{game_mode}-{sequence}` (e.g., `classic-classic-0`)
 - **Leaderboard Page:** Four tabs (Today, Daily, Weekly, History) accessible via `?page=today|daily|weekly|history`
@@ -203,6 +203,7 @@ HF_WORD_LIST_REPO_ID=YourUsername/WordRepo  # Dataset repo for AI word lists
 
 # OAuth Admin Access (NEW)
 ADMIN_USERS=username1,username2        # Comma-separated list of admin usernames
+MAX_DISPLAY_ENTRIES=25                 # Max leaderboard entries to display (default: 25)
 ```
 
 ### HF_REPO_ID Structure

README.md

@@ -84,13 +84,13 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
 
 ### 🏆 Daily & Weekly Leaderboards (v0.2.1) ✅
 **Comprehensive Leaderboard System:**
-- **Daily Leaderboards:** Top 20 scores for each day (resets UTC midnight)
-- **Weekly Leaderboards:** Top 20 scores for each ISO week (resets Monday UTC 00:00)
+- **Daily Leaderboards:** Top 25 scores for each day (resets UTC midnight)
+- **Weekly Leaderboards:** Top 25 scores for each ISO week (resets Monday UTC 00:00)
 - **Settings-Based Separation:** Each unique combination of game settings creates a separate leaderboard
   - Settings include: game_mode, wordlist_source, show_incorrect_guesses, enable_free_letters, puzzle_options
   - You compete only with players using identical settings
 - **Sorting:** Scores sorted by: score (desc) → time (asc) → difficulty (desc)
-- **Qualification:** Only top 20 scores displayed per leaderboard (more can be stored)
+- **Qualification:** Only top 25 scores displayed per leaderboard (more can be stored)
 - **Storage:** Folder-based discovery in HuggingFace repo (no index.json)
   - Path: `games/leaderboards/{daily|weekly}/{period}/{file_id}/settings.json`
   - File ID format: `{wordlist_source}-{game_mode}-{sequence}` (e.g., `classic-classic-0`)
@@ -195,6 +195,7 @@ SPACE_NAME=YourUsername/Wrdler         # Your HF Space name
 
 # Optional
 CRYPTO_PK=                             # Reserved for future signing
+MAX_DISPLAY_ENTRIES=25                 # Max leaderboard entries to display (default: 25)
 ```
 
 **How to get your HF_API_TOKEN:**
@@ -251,7 +252,7 @@ All test files must be placed in the `/tests` folder. This ensures a clean proje
 **Daily and Weekly Leaderboards Improved**
 - ✅ Settings-based leaderboard separation (unique leaderboards per settings combo)
 - ✅ Folder-based discovery system (no index.json)
-- ✅ Top 20 displayed entries per leaderboard
+- ✅ Top 25 displayed entries per leaderboard
 - ✅ Four-tab leaderboard page (Today, Daily, Weekly, History)
 - ✅ Automatic score qualification and submission
 - ✅ Query parameter filtering for direct links (`?gidd=`, `?gidw=`)

env.template

@@ -21,3 +21,4 @@ CRYPTO_PK=btc_public_key_here
 IS_LOCAL=true
 USE_HF_WORDS=false
 HF_WORD_LIST_REPO_ID=hf_username/word-lists
+MAX_DISPLAY_ENTRIES=25

specs/leaderboard_spec.md

@@ -30,8 +30,8 @@
 
 This specification documents the implemented **Daily and Weekly Leaderboard System** for Wrdler. The system:
 
-- ✅ Tracks top 20 scores for daily leaderboards (resets at UTC midnight)
-- ✅ Tracks top 20 scores for weekly leaderboards (resets at UTC Monday 00:00)
+- ✅ Tracks top 25 scores for daily leaderboards (resets at UTC midnight)
+- ✅ Tracks top 25 scores for weekly leaderboards (resets at UTC Monday 00:00)
 - ✅ Creates separate leaderboards for each unique combination of game-affecting settings
 - ✅ Automatically adds qualifying scores from any game completion (including challenge mode)
 - ✅ Provides a dedicated leaderboard page with historical lookup capabilities
@@ -49,9 +49,9 @@ This specification documents the implemented **Daily and Weekly Leaderboard Syst
 
 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., `games/leaderboards/daily/2025-01-27/`)
+2. **Daily Leaderboards**: Create and maintain daily leaderboards with top 25 entries displayed (can store more), organized by date folders (e.g., `games/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., `games/leaderboards/weekly/2025-W04/`)
+3. **Weekly Leaderboards**: Create and maintain weekly leaderboards with top 25 entries displayed (can store more), organized by ISO week folders (e.g., `games/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
 
@@ -194,7 +194,7 @@ Instead of maintaining an `index.json` file, leaderboards are discovered by:
 ┌─────────────────────┐
 │ Check if score      │
 │ qualifies (top      │
-│ 20 displayed)       │
+│ 25 displayed)       │
 └─────────────────────┘
           │
           ▼
@@ -250,7 +250,7 @@ Both leaderboard files and challenge files use the **same base structure**. The
   "enable_free_letters": true,
   "wordlist_source": "classic.txt",
   "game_title": "Wrdler Gradio AI",
-  "max_display_entries": 20
+  "max_display_entries": 25
 }
 ```
 
@@ -270,7 +270,7 @@ Both leaderboard files and challenge files use the **same base structure**. The
 | `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) |
+| `max_display_entries` | int | Maximum entries to display (default 25, configurable via MAX_DISPLAY_ENTRIES env var) |
 
 ### 4.4 User Entry Schema
 
@@ -667,7 +667,7 @@ The following represents the actual implementation as of v0.2.0:
 - ✅ `find_matching_leaderboard()` with prefix filtering and full verification
 - ✅ `create_or_get_leaderboard()` with automatic sequence management
 - ✅ `submit_score_to_all_leaderboards()` as main entry point
-- ✅ `check_qualification()` for top 20 filtering
+- ✅ `check_qualification()` for top 25 filtering
 - ✅ Period ID generators: `get_current_daily_id()`, `get_current_weekly_id()`
 - ✅ Historical lookup functions: `list_available_periods()`, `list_settings_for_period()`
 - ✅ URL generation with `get_leaderboard_url()`
@@ -753,7 +753,7 @@ HF_REPO_ID/games/
 #### Known Limitations (as of v0.2.0)
 
 1. **No caching:** Each page load fetches from HF repository (can be slow)
-2. **No pagination:** Displays top 20 only (additional entries stored but not shown)
+2. **No pagination:** Displays top 25 only (additional entries stored but not shown)
 3. **Limited error handling:** Basic logging, could benefit from retry logic
 4. **No rate limiting:** Submission frequency not constrained
 5. **No archival:** Old leaderboards remain indefinitely (no cleanup script)
@@ -761,7 +761,7 @@ HF_REPO_ID/games/
 #### Future Enhancements (Planned for v0.3.0+)
 
 - ⏳ In-memory caching with TTL (60s for periods, 15s for leaderboards)
-- ⏳ Pagination for >20 entries
+- ⏳ Pagination for >25 entries
 - ⏳ Retry logic with exponential backoff
 - ⏳ Rate limiting per IP/session
 - ⏳ Archival script for old periods (>365 days daily, >156 weeks weekly)
@@ -833,7 +833,7 @@ HF_REPO_ID/games/
   - Provide a maintenance script to prune old periods and reindex cache.
 - Privacy:
   - Store only display names and gameplay metrics; avoid PII.
-  - Users may choose “Anonymous”; do not display IP or identifiers publicly.
+  - Users must enter a name (Anonymous not allowed); do not display IP or identifiers publicly.
 
 ### 14.6 Time and Period Boundaries
 

specs/requirements.md

@@ -232,13 +232,15 @@ This document breaks down the implementation tasks for Wrdler using the game rul
   - Scans folders for period IDs
   - Filters by file_id prefix
   - Loads and verifies full settings match
-- ✅ **Top 20 Display:** Sorted by score → time → difficulty
+- ✅ **Top 25 Display:** Sorted by score → time → difficulty
+- **Sorting:** Scores sorted by: score (desc) → time (asc) → difficulty (desc)
+- **Qualification:** Only top 25 (configurable) scores displayed per leaderboard (more can be stored)
 - ✅ **Automatic Submission:** From game over popup
 - ✅ **Challenge Integration:** Tracks source_challenge_id
 
 **Storage Structure:**
 ```
-games/
+HF_REPO_ID/games/
 ├── leaderboards/
 │   ├── daily/{YYYY-MM-DD}/{file_id}/settings.json
 │   └── weekly/{YYYY-Www}/{file_id}/settings.json
@@ -278,13 +280,13 @@ games/
 - `get_current_daily_id()` / `get_current_weekly_id()` - Period ID generators
 
 **Privacy:**
-- Only stores: username (optional), score, time, word_list, difficulty
-- No PII beyond optional player name
+- Only stores: username (required), score, time, word_list, difficulty
+- No PII beyond required player name
 - All data in HuggingFace repository
 
 **Known Limitations (v0.2.1):**
 - No caching (future)
-- No pagination beyond top 20
+- No pagination beyond top 25
 - Basic error handling
 - No rate limiting
 - No archival script

specs/specs.md

@@ -104,7 +104,7 @@ Wrdler features a comprehensive daily and weekly leaderboard system:
   - `enable_free_letters` (boolean)
   - `puzzle_options` (spacer, may_overlap)
 - **Sorting:** Scores sorted by: score (desc) → time (asc) → difficulty (desc)
-- **Qualification:** Only top 20 scores displayed per leaderboard (more can be stored)
+- **Qualification:** Only top 25 (configurable) scores displayed per leaderboard (more can be stored)
 
 **Storage Structure:**
 ```

wrdler/__init__.py

@@ -9,5 +9,5 @@ Key differences from BattleWords:
 - Daily and weekly leaderboards
 """
 
-__version__ = "0.2.4"
+__version__ = "0.2.5"
 __all__ = ["models", "generator", "logic", "ui", "word_loader", "leaderboard", "leaderboard_page"]

wrdler/leaderboard.py

@@ -6,7 +6,7 @@ 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)
+- Max display entries: 25 per leaderboard (can store more)
 - Daily reset: UTC midnight
 - Weekly reset: Monday UTC 00:00 (ISO week)
 - Sorting: score (desc), time (asc), difficulty (desc)
@@ -23,7 +23,7 @@ File ID Format:
   {wordlist_source}-{game_mode}-{sequence}
   Example: classic-classic-0, easy-easy-1
 """
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 from dataclasses import dataclass, field
 from datetime import datetime, timezone, timedelta
@@ -36,13 +36,13 @@ from wrdler.modules.storage import (
     _upload_json_to_repo,
     _list_repo_folders
 )
-from wrdler.modules.constants import HF_REPO_ID, APP_SETTINGS
+from wrdler.modules.constants import HF_REPO_ID, APP_SETTINGS, MAX_DISPLAY_ENTRIES
 from wrdler.game_storage import generate_uid
 
 logger = logging.getLogger(__name__)
 
 # Configuration
-MAX_DISPLAY_ENTRIES = 20
+# MAX_DISPLAY_ENTRIES = 30 from environmental variables in constants.py
 LEADERBOARD_BASE_PATH = "games/leaderboards"
 DAILY_LEADERBOARD_PATH = f"{LEADERBOARD_BASE_PATH}/daily"
 WEEKLY_LEADERBOARD_PATH = f"{LEADERBOARD_BASE_PATH}/weekly"
@@ -636,10 +636,10 @@ def check_qualification(
     word_list_difficulty: Optional[float] = None
 ) -> bool:
     """
-    Check if a score qualifies for the leaderboard display (top 20).
+    Check if a score qualifies for the leaderboard display (top 30).
 
-    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.
+    Note: The leaderboard can store more than 30 entries, but only top 30 are displayed.
+    This function checks if the score would be in the top 30.
 
     Args:
         leaderboard: Existing leaderboard (or None if new)
@@ -653,7 +653,7 @@ def check_qualification(
     if leaderboard is None or len(leaderboard.users) < MAX_DISPLAY_ENTRIES:
         return True
 
-    # Get the 20th entry (last displayed)
+    # Get the 30th entry (last displayed)
     display_users = leaderboard.get_display_users()
     if len(display_users) < MAX_DISPLAY_ENTRIES:
         return True
@@ -695,7 +695,7 @@ def get_leaderboard_url(entry_type: EntryType, period_id: str, file_id: str, bas
     
     # Determine base URL (use current host or default to production)
     if base_url is None:
-        # Try to get from environment or default to production space
+        # Try to get from environment or default to production
         import os
         from wrdler.modules.constants import SPACE_NAME
         
@@ -775,7 +775,7 @@ def submit_to_leaderboard(
             break
 
     if rank is None:
-        # Entry was sorted out of top 20
+        # Entry was sorted out of top 30
         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)

wrdler/leaderboard_page.py

@@ -134,7 +134,9 @@ def _render_leaderboard_table(leaderboard: Optional[LeaderboardSettings], title:
                                              'text-align: center; color: #20d46c; font-weight: bold;' if col == 'Score' else 
                                              'text-align: center;' for col in df.columns], axis=1)
         
-        st.dataframe(styled_df, use_container_width=True, hide_index=True)
+        # Calculate height to show all rows (approx 35px per row + 38px header)
+        height = (len(df) + 1) * 35 + 3
+        st.dataframe(styled_df, use_container_width=True, hide_index=True, height=height)
 
     # Show entry count and last updated
     total_entries = len(leaderboard.users)
@@ -358,7 +360,7 @@ def _render_history_tab():
 
     with col2:
         st.subheader("Weekly History")
-        weekly_periods = list_available_periods("weekly", limit=20)
+        weekly_periods = list_available_periods("weekly", limit=6)
         if weekly_periods:
             selected_weekly = st.selectbox(
                 "Select a week",

wrdler/modules/constants.py

@@ -25,6 +25,7 @@ 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")
+MAX_DISPLAY_ENTRIES = int(os.getenv("MAX_DISPLAY_ENTRIES", 25))
 
 # List of smaller, faster fallback models if the primary one fails
 AI_MODELS = [
@@ -80,6 +81,7 @@ def load_settings() -> Dict[str, Any]:
         "words_per_puzzle": 6,
         "free_letters_count": 2,
         "max_incorrect_guesses": 10,
+        "max_display_entries": MAX_DISPLAY_ENTRIES,
     }
 
     try:

wrdler/ui.py

@@ -545,7 +545,7 @@ border-radius: 50% !important;
             position:relative;
             z-index: 1200;
             }
-          .username_input [id^="text_input"], .st-key-username_input [id^="text_input"] { color: #fff;}
+          .username_input [id^="text_input"], .st-key-username_input [id^="text_input"] { color: #666;}
           .st-emotion-cache-18kf3ut, .stColumn.st-emotion-cache-116javk {padding-bottom:3px;}
 
           /* grid adjustments */
@@ -2038,15 +2038,15 @@ def _game_over_content(state: GameState) -> None:
             st.session_state["player_username"] = ""
 
         username = st.text_input(
-            "Enter your name (optional)",
+            "Enter your name (required)",
             value=st.session_state.get("player_username", ""),
             key="username_input",
-            placeholder="Anonymous"
+            placeholder="Your Name"
         )
         if username:
             st.session_state["player_username"] = username
-        else:
-            username = "Anonymous"
+        
+        can_submit = bool(username and username.strip())
 
         # Helper function to submit to leaderboards
         def _submit_to_leaderboards(username: str, score: int, time_secs: int, word_list: list, challenge_id: str = None):
@@ -2105,7 +2105,10 @@ def _game_over_content(state: GameState) -> None:
         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"
 
-            if st.button(button_text, key="generate_share_link", use_container_width=True):
+            if not can_submit:
+                st.warning("⚠️ Please enter your name to submit.")
+
+            if st.button(button_text, key="generate_share_link", use_container_width=True, disabled=not can_submit):
                 try:
                     # Extract game data
                     word_list = [w.text for w in state.puzzle.words]
@@ -2186,7 +2189,7 @@ def _game_over_content(state: GameState) -> None:
             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):
+                if st.button("🏆 Submit to Leaderboards", key="submit_leaderboard_only", use_container_width=True, disabled=not can_submit):
                     try:
                         word_list = [w.text for w in state.puzzle.words]
                         lb_results = _submit_to_leaderboards(