Leaderboard Page Identity Update

specs/leaderboard_spec.md

@@ -1,6 +1,6 @@
-# Wrdler Leaderboard System Specification
+# Wrdler Leaderboard System Specification
 
-**Document Version:** 1.3.0  
+**Document Version:** 1.3.1  
 **Target Project Version:** 0.2.0  
 **Author:** GitHub Copilot  
 **Date:** 2025-01-27  
@@ -22,6 +22,7 @@
 10. [UI Components](#10-ui-components)
 11. [Testing Requirements](#11-testing-requirements)
 12. [Migration Notes](#12-migration-notes)
+13. [Operational Considerations](#13-operational-considerations)
 
 ---
 
@@ -92,29 +93,29 @@ Each date/week has settings-based subfolders. The folder name (file_id) encodes
 
 ```
 HF_REPO_ID/
-??? games/                          # All game-related storage
-?   ??? {challenge_id}/             # Existing challenge storage
-?   ?   ??? settings.json           # entry_type: "challenge"
-?   ??? leaderboards/
-?       ??? daily/
-?       ?   ??? 2025-01-27/
-?       ?   ?   ??? classic-classic-0/
-?       ?   ?   ?   ??? settings.json
-?       ?   ?   ??? easy-easy-0/
-?       ?   ?       ??? settings.json
-?       ?   ??? 2025-01-26/
-?       ?       ??? classic-classic-0/
-?       ?           ??? settings.json
-?       ??? weekly/
-?           ??? 2025-W04/
-?           ?   ??? classic-classic-0/
-?           ?   ?   ??? settings.json
-?           ?   ??? easy-too_easy-0/
-?           ?       ??? settings.json
-?           ??? 2025-W03/
-?               ??? classic-classic-0/
-?                   ??? settings.json
-??? shortener.json                  # Existing URL shortener
+├── games/                          # All game-related storage
+│   ├── {challenge_id}/             # Existing challenge storage
+│   │   └── settings.json           # entry_type: "challenge"
+│   └── leaderboards/
+│       ├── daily/
+│       │   ├── 2025-01-27/
+│       │   │   ├── classic-classic-0/
+│       │   │   │   └── settings.json
+│       │   │   └── easy-easy-0/
+│       │   │       └── settings.json
+│       │   └── 2025-01-26/
+│       │       └── classic-classic-0/
+│       │           └── settings.json
+│       └── weekly/
+│           ├── 2025-W04/
+│           │   ├── classic-classic-0/
+│           │   │   └── settings.json
+│           │   └── easy-too_easy-0/
+│           │       └── settings.json
+│           └── 2025-W03/
+│               └── classic-classic-0/
+│                   └── settings.json
+└── shortener.json                  # Existing URL shortener
 ```
 
 ### 3.2 File ID Format
@@ -153,52 +154,52 @@ Instead of maintaining an `index.json` file, leaderboards are discovered by:
 ### 3.4 Data Flow
 
 ```
-??????????????????????
-?  Game Completion   ?
-??????????????????????
-          ?
-          ?
-??????????????????????
-? Get current game   ?
-? settings           ?
-??????????????????????
-          ?
-          ?
-??????????????????????
-? Build file_id      ?
-? prefix from        ?
-? settings           ?
-??????????????????????
-          ?
-          ?
-??????????????????????
-? Scan folders for   ?
-? matching file_id   ?
-? or create new      ?
-??????????????????????
-          ?
-    ?????????????
-    ?           ?
-    ?           ?
-????????? ?????????????
-? Daily ? ? Weekly    ?
-? LB    ? ? LB        ?
-????????? ?????????????
-    ?          ?
-    ????????????
-         ?
-         ?
-???????????????????????
-? Check if score      ?
-? qualifies (top      ?
-? 20 displayed)       ?
-???????????????????????
-          ?
-          ?
-???????????????????????
-? Update & Upload     ?
-? to HF repo          ?
-???????????????????????
+┌────────────────────┐
+│  Game Completion   │
+└────────────────────┘
+          │
+          ▼
+┌────────────────────┐
+│ Get current game   │
+│ settings           │
+└────────────────────┘
+          │
+          ▼
+┌────────────────────┐
+│ Build file_id      │
+│ prefix from        │
+│ settings           │
+└────────────────────┘
+          │
+          ▼
+┌────────────────────┐
+│ Scan folders for   │
+│ matching file_id   │
+│ or create new      │
+└────────────────────┘
+          │
+    ┌─────┴─────┐
+    │           │
+    ▼           ▼
+┌───────┐ ┌───────────┐
+│ Daily │ │ Weekly    │
+│ LB    │ │ LB        │
+└───────┘ └───────────┘
+    │          │
+    └────┬─────┘
+         │
+         ▼
+┌─────────────────────┐
+│ Check if score      │
+│ qualifies (top      │
+│ 20 displayed)       │
+└─────────────────────┘
+          │
+          ▼
+┌─────────────────────┐
+│ Update & Upload     │
+│ to HF repo          │
+└─────────────────────┘
 ```
 
 ---
@@ -524,7 +525,7 @@ Add to `_render_sidebar()` in `ui.py`:
 
 ```python
 st.header("Navigation")
-if st.button("?? Leaderboards", use_container_width=True):
+if st.button("🏆 Leaderboards", use_container_width=True):
     st.session_state["show_leaderboard_page"] = True
     st.rerun()
 ```
@@ -539,9 +540,9 @@ Modify `_game_over_content()` in `ui.py` to:
 ```python
 # After score submission
 if results["daily"]["qualified"]:
-    st.success(f"?? You ranked #{results['daily']['rank']} on today's leaderboard!")
+    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!")
+    st.success(f"🏆 You ranked #{results['weekly']['rank']} on this week's leaderboard!")
 ```
 
 ### 10.3 Leaderboard Page Routing
@@ -553,7 +554,7 @@ In `run_app()`:
 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"):
+    if st.button("← Back to Game"):
         st.session_state["show_leaderboard_page"] = False
         st.rerun()
     return  # Don't render game UI
@@ -606,7 +607,7 @@ class TestDateIds:
 
 ### Integration Tests
 
-- Test full flow: game completion ? leaderboard submission ? retrieval
+- Test full flow: game completion → leaderboard submission → retrieval
 - Test with mock HuggingFace repository
 - Test folder-based discovery logic
 - Test concurrent submissions (edge case)
@@ -647,67 +648,108 @@ class TestDateIds:
 
 ---
 
-## Appendix A: Example Daily Leaderboard JSON (Folder-Based)
-
-**Path:** `games/leaderboards/daily/2025-01-27/classic-classic-0/settings.json`
-
-```json
-{
-  "challenge_id": "2025-01-27/classic-classic-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: File ID Examples
-
-| Wordlist Source | Game Mode | Sequence | File ID |
-|-----------------|-----------|----------|---------|
-| `classic.txt` | `classic` | 0 | `classic-classic-0` |
-| `easy.txt` | `easy` | 0 | `easy-easy-0` |
-| `classic.txt` | `too easy` | 1 | `classic-too_easy-1` |
-| `fourth_grade.txt` | `classic` | 0 | `fourth_grade-classic-0` |
-
----
-
-## Appendix C: Entry Type Comparison (Updated)
-
-| Field | daily | weekly | challenge |
-|-------|-------|--------|-----------|
-| `challenge_id` format | `"2025-01-27/classic-classic-0"` | `"2025-W04/easy-easy-0"` | `"20251130T190249Z-ABC123"` |
-| `entry_type` | `"daily"` | `"weekly"` | `"challenge"` |
-| Storage path | `games/leaderboards/daily/{date}/{file_id}/settings.json` | `games/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 (file_id encodes settings) | Yes (file_id encodes settings) | N/A (settings fixed per challenge) |
-| `max_display_entries` | 20 | 20 | N/A (all users shown) |
-| Discovery method | Folder scan + prefix match | Folder scan + prefix match | Direct by ID |
-
----
-
-*End of Specification*
+## 13. Operational Considerations
+
+### 13.1 Concurrency and Consistency
+
+- Write model:
+  - Use optimistic concurrency: read `settings.json`, merge new `users` entry, write back with a unique commit message including `challenge_id` and `uid`.
+  - Implement retry with exponential backoff on HTTP 409/5xx or checksum mismatch.
+  - Ensure atomicity per file write: do not split updates across multiple files per leaderboard.
+- Simultaneous file creation:
+  - When no matching `file_id` folder exists, first attempt creation; if a concurrent process creates it, fallback to loading and merging.
+  - Always re-verify settings match by reading `settings.json` after folder discovery.
+- Sequence collisions:
+  - If `{wordlist}-{mode}-{sequence}` collides but settings differ, increment `sequence` until a unique folder is found; verify match via file content, not only prefix.
+
+### 13.2 Caching and Discovery Performance
+
+- Cache tiers:
+  - In-memory (per app session): 
+    - Period listings for `games/leaderboards/{type}/` (TTL 60s).
+    - `file_id` listings inside a period (TTL 30s).
+    - Loaded `settings.json` for leaderboards (TTL 15s or invalidated on write).
+- Invalidation:
+  - On successful submission, invalidate the specific leaderboard cache (file content and directory listing for that period).
+  - Provide a manual refresh option in UI (leaderboard page).
+- Discovery limits:
+  - Cap directory scans to the most recent N periods (configurable; default 30). UI uses explicit period selection for older data.
+  - Prefer prefix filtering client-side before loading file content.
+
+### 13.3 Error Handling and Observability
+
+- Error taxonomy:
+  - Storage errors: `HF_STORAGE_UNAVAILABLE`, `HF_WRITE_CONFLICT`, `HF_NOT_FOUND`.
+  - Validation errors: `LB_INVALID_INPUT`, `LB_SETTINGS_MISMATCH`.
+  - Operational errors: `LB_TIMEOUT`, `LB_RETRY_EXCEEDED`.
+- User feedback:
+  - On non-critical failure (e.g., leaderboard write conflict), show non-blocking warning and retry silently up to 3 times.
+- Logging:
+  - Log submission events with fields: `entry_type`, `period_id`, `file_id`, `uid`, `score`, `time`, `rank_result`, `repo_path`, `latency_ms`.
+  - Log error events with `code`, `message`, `attempt`, `backoff_ms`.
+- Telemetry (optional):
+  - Count successful submissions per period and per settings combination for basic monitoring.
+
+### 13.4 Security and Abuse Controls
+
+- Input validation:
+  - `username`: max 40 chars, strip control chars, allow alphanumerics, spaces, basic punctuation; reject offensive content if possible.
+  - `word_list`: array of 6 uppercase A–Z strings, length 3–10; drop invalid entries.
+  - `score`: 0–999; `time`: 1–36000 (10 hours); `word_list_difficulty`: float if provided, clamp to 0–10000.
+- Spam and duplicates:
+  - Rate limit per IP/session (e.g., max 10 submissions per hour).
+  - Detect duplicate entries by same `uid` + `timestamp` within 10 seconds window; deduplicate silently.
+- Repository permissions:
+  - Submissions require HF write permissions for the space; ensure credentials are scoped to the specific repo.
+  - Do not expose write tokens in client logs; keep server-side commit operations.
+
+### 13.5 Data Lifecycle and Retention
+
+- Retention:
+  - Keep daily leaderboards for 365 days; weekly leaderboards for 156 weeks (3 years).
+  - Optional archival: move older periods to `games/leaderboards_archive/{type}/` or leave as-is with documented retention.
+- Cleanup:
+  - 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.
+
+### 13.6 Time and Period Boundaries
+
+- Timezone:
+  - All operations use UTC. The periods roll over at 00:00:00 UTC for daily, Monday 00:00:00 UTC for weekly.
+- ISO week:
+  - Use Python’s `isocalendar()` to derive `YYYY-Www` and handle year transitions (weeks spanning year boundaries).
+- Clock source:
+  - Use server-side timestamp for submissions; do not trust client clock. If unavailable, fall back to Python `datetime.utcnow()`.
+
+### 13.7 UI Reliability and UX
+
+- Loading states:
+  - Show skeleton/loading indicators while scanning folders or reading leaderboard JSON.
+- Empty states:
+  - Display “No entries yet” when a leaderboard exists without users or has not been created.
+- Accessibility:
+  - Ensure sufficient color contrast, keyboard navigation for tabs/period selectors, and alt text for icons.
+- Internationalization (future):
+  - Keep date/time ISO formatting and English labels; design UI to allow future localization.
+
+### 13.8 Ranking and Tie-Breaks (Operational Clarification)
+
+- Sort order:
+  - Primary: `score` desc; secondary: `time` asc; tertiary: `word_list_difficulty` desc; quaternary: stable by `timestamp` asc.
+- Display limit:
+  - Always store full `users` list; apply `max_display_entries` at render time only.
+- Rank reporting:
+  - Return rank based on full sorted list even if not displayed; if outside display limit, mark `qualified=False`.
+
+### 13.9 Commit and Retry Strategy (HF)
+
+- Commit messages:
+  - Format: `leaderboard:{entry_type}:{period_id}:{file_id} add uid={uid} score={score} time={time}`.
+- Retries:
+  - Backoff sequence: 0.25s, 0.5s, 1s; max 3 attempts; abort on `LB_SETTINGS_MISMATCH`.
+- Partial failures:
+  - If daily succeeds and weekly fails (or vice versa), return both statuses independently; UI reports partial success.
+
+---

wrdler/leaderboard_page.py

@@ -9,7 +9,7 @@ __version__ = "0.2.0"
 
 import streamlit as st
 from datetime import datetime
-from typing import Optional
+from typing import Optional, Tuple
 import pandas as pd
 
 from wrdler.leaderboard import (
@@ -44,6 +44,17 @@ def _get_rank_emoji(rank: int) -> str:
     return f"{rank}."
 
 
+def _settings_badge(lb: LeaderboardSettings) -> str:
+    """Build a compact settings badge for headers."""
+    mode = lb.game_mode
+    source = lb.wordlist_source
+    incorrect = "errors:on" if lb.show_incorrect_guesses else "errors:off"
+    free = "free:on" if lb.enable_free_letters else "free:off"
+    spacer = lb.puzzle_options.get("spacer", 0)
+    overlap = lb.puzzle_options.get("may_overlap", False)
+    return f"[{mode} • {source} • {incorrect} • {free} • spacer:{spacer} • overlap:{'yes' if overlap else 'no'}]"
+
+
 def _render_leaderboard_table(leaderboard: Optional[LeaderboardSettings], title: str):
     """Render a leaderboard as a styled table."""
     if title:
@@ -61,7 +72,7 @@ def _render_leaderboard_table(leaderboard: Optional[LeaderboardSettings], title:
     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 "-"
+        difficulty = f"{user.word_list_difficulty:.2f}" if user.word_list_difficulty is not None else "-"
         
         # Show challenge indicator if from a challenge
         challenge_badge = " 🎯" if user.source_challenge_id else ""
@@ -118,6 +129,22 @@ def render_leaderboard_page(default_tab: str = "daily"):
     game_title = APP_SETTINGS.get("game_title", "Wrdler")
     st.title(f"🏆 {game_title} Leaderboards")
 
+    # Inject CSS to style the active tab
+    st.markdown(
+        """
+        <style>
+          /* Target Streamlit tabs: pick the selected tab button/link */
+          div[role="tablist"] p {padding: 0.5em 1em !important;}
+          div[role="tablist"] [aria-selected="true"] {
+            color: #ffffff !important;
+            border: 1px solid #4CAF50 !important;            
+          }
+          div[role="tablist"] [aria-selected="true"] p {font-weight: bold !important;}
+        </style>
+        """,
+        unsafe_allow_html=True
+    )
+
     # Tab selection - set default based on parameter
     tab_names = ["📅 Daily", "📆 Weekly", "📚 History"]
     
@@ -139,48 +166,73 @@ def _render_daily_tab():
     st.header("📅 Daily Leaderboards")
     st.write(f"Top {MAX_DISPLAY_ENTRIES} scores for each day. Resets at UTC midnight.")
 
-    # Get current game settings for filtering
-    settings = _get_current_game_settings()
-    st.info(f"Showing leaderboards for: **{settings.game_mode}** mode, **{settings.wordlist_source}**")
-
-    # Get last 7 days
-    daily_boards = get_last_n_daily_leaderboards(7, settings)
+    # Show last 7 days; for each day, show all leaderboards (settings combos)
+    daily_periods = list_available_periods("daily", limit=7)
+    if not daily_periods:
+        st.info("No daily leaderboards found.")
+        return
 
-    for date_id, leaderboard in daily_boards:
-        # Format date nicely
+    for date_id in daily_periods:
+        # Human friendly date title
         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")
+            is_today = date_id == get_current_daily_id()
+            date_title = ("🌟 Today " if is_today else "") + 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, "")
+            date_title = date_id
+
+        # List all settings folders (file_ids) for this period
+        settings_list = list_settings_for_period("daily", date_id)
+        if not settings_list:
+            with st.expander(date_title, expanded=False):
+                st.info("No leaderboards for this date.")
+            continue
+
+        # Render one expander per settings combination
+        for settings_info in settings_list:
+            file_id = settings_info["file_id"]
+            lb = load_leaderboard("daily", date_id, file_id)
+            header_suffix = ""
+            if lb is not None:
+                header_suffix = _settings_badge(lb)
+            expander_title = f"{date_title} {header_suffix}" if header_suffix else date_title
+            with st.expander(expander_title, expanded=(date_id == get_current_daily_id())):
+                # Also show a small settings summary above the table
+                if lb is not None:
+                    st.caption(f"Settings: mode={lb.game_mode}, source={lb.wordlist_source}, show_incorrect={lb.show_incorrect_guesses}, free_letters={lb.enable_free_letters}, spacer={lb.puzzle_options.get('spacer', 0)}, overlap={lb.puzzle_options.get('may_overlap', False)}")
+                _render_leaderboard_table(lb, "")
 
 
 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.")
-
-    # Get current game settings for filtering
-    settings = _get_current_game_settings()
-    st.info(f"Showing leaderboard for: **{settings.game_mode}** mode, **{settings.wordlist_source}**")
+    st.header("📆 Weekly Leaderboards")
+    st.write(f"Top {MAX_DISPLAY_ENTRIES} scores for each ISO week. Resets Monday at UTC midnight.")
 
     weekly_id = get_current_weekly_id()
-    _, leaderboard = find_matching_leaderboard("weekly", weekly_id, settings)
 
-    # Parse week for display
+    # Show current week; render all settings combinations that exist
+    settings_list = list_settings_for_period("weekly", weekly_id)
+    if not settings_list:
+        st.info("No weekly leaderboards found for the current week.")
+        return
+
     try:
         year, week = weekly_id.split("-W")
-        title = f"Week {int(week)}, {year}"
+        week_title = f"Week {int(week)}, {year}"
     except ValueError:
-        title = weekly_id
+        week_title = weekly_id
 
-    _render_leaderboard_table(leaderboard, f"🗓️ {title}")
+    for settings_info in settings_list:
+        file_id = settings_info["file_id"]
+        lb = load_leaderboard("weekly", weekly_id, file_id)
+        header_suffix = ""
+        if lb is not None:
+            header_suffix = _settings_badge(lb)
+        expander_title = f"🗓️ {week_title} {header_suffix}" if header_suffix else f"🗓️ {week_title}"
+        with st.expander(expander_title, expanded=True):
+            if lb is not None:
+                st.caption(f"Settings: mode={lb.game_mode}, source={lb.wordlist_source}, show_incorrect={lb.show_incorrect_guesses}, free_letters={lb.enable_free_letters}, spacer={lb.puzzle_options.get('spacer', 0)}, overlap={lb.puzzle_options.get('may_overlap', False)}")
+            _render_leaderboard_table(lb, "")
 
 
 def _render_history_tab():
@@ -200,7 +252,6 @@ def _render_history_tab():
                 key="history_daily_select"
             )
 
-            # Show available settings for this period
             settings_list = list_settings_for_period("daily", selected_daily)
             if settings_list:
                 file_id_options = [s["file_id"] for s in settings_list]
@@ -213,7 +264,10 @@ def _render_history_tab():
 
                 if st.button("Load Daily", key="load_daily"):
                     leaderboard = load_leaderboard("daily", selected_daily, selected_file_id)
-                    _render_leaderboard_table(leaderboard, f"Daily: {selected_daily} ({selected_file_id})")
+                    header = f"Daily: {selected_daily} "
+                    if leaderboard is not None:
+                        header += _settings_badge(leaderboard)
+                    _render_leaderboard_table(leaderboard, header)
             else:
                 st.info("No leaderboards found for this date.")
         else:
@@ -229,7 +283,6 @@ def _render_history_tab():
                 key="history_weekly_select"
             )
 
-            # Show available settings for this period
             settings_list = list_settings_for_period("weekly", selected_weekly)
             if settings_list:
                 file_id_options = [s["file_id"] for s in settings_list]
@@ -242,7 +295,10 @@ def _render_history_tab():
 
                 if st.button("Load Weekly", key="load_weekly"):
                     leaderboard = load_leaderboard("weekly", selected_weekly, selected_file_id)
-                    _render_leaderboard_table(leaderboard, f"Weekly: {selected_weekly} ({selected_file_id})")
+                    header = f"Weekly: {selected_weekly} "
+                    if leaderboard is not None:
+                        header += _settings_badge(leaderboard)
+                    _render_leaderboard_table(leaderboard, header)
             else:
                 st.info("No leaderboards found for this week.")
         else: