v0.2.3 Update Leaderboard titles to daterange

CLAUDE.md

@@ -41,6 +41,13 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords:
 - Remote storage via HuggingFace datasets
 - Word list difficulty calculation
 - "Show Challenge Share Links" toggle (default OFF)
+- **Integration:**
+  - Automatic submission after game completion (opt-in via game over popup)
+  - Challenge scores also contribute to daily/weekly leaderboards
+  - Source tracking via `source_challenge_id` field
+  - Unified JSON format with `entry_type` field (daily/weekly/challenge)
+
+**Access:** 'Leaderboard' link in the footer navigation at the bottom of the page
 
 ### Daily & Weekly Leaderboards
 - **Settings-Based Separation:** Each unique settings combo creates separate leaderboard
@@ -55,7 +62,7 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords:
   2025-12-08 00:00:00 UTC to 2025-12-08 23:59:59 UTC
   and
   2025-12-07 16:00:00 PST to 2025-12-08 15:59:59 PST
-  The leaderboard expander label should show: `Monday, December 08, 2025 4:00 PM PST – Tuesday, December 09, 2025 3:59:59 PM PST [settings badge]`
+  The leaderboard expander label should show: `Mon, Dec 08, 2025 4:00 PM PST – Tue, Dec 09, 2025 3:59:59 PM PST [settings badge]`
 
 ### AI Word Generation
 - Topic-based word list generation via HuggingFace Spaces or local transformers

README.md

@@ -98,7 +98,7 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
   - Leaderboard files store UTC dates/times for each period.
   - When viewing daily leaderboards, the app displays the UTC period as a PST date range:
     - For example, a UTC file date of `2025-12-08` covers `2025-12-08 00:00:00 UTC` to `2025-12-08 23:59:59 UTC`, which is displayed as `2025-12-07 16:00:00 PST` to `2025-12-08 15:59:59 PST`.
-    - The leaderboard expander label should show: `Monday, December 08, 2025 4:00 PM PST – Tuesday, December 09, 2025 3:59:59 PM PST [settings badge]`
+    - The leaderboard expander label should show: `Mon, Dec 08, 2025 4:00 PM PST – Tue, Dec 09, 2025 3:59:59 PM PST [settings badge]`
     - Daily leaderboards display the date range in PST for easier local time understanding.
     - Weekly leaderboards use ISO week dates (e.g., `2025-W49`) and are available every Monday.
 
@@ -115,7 +115,7 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
 - Source tracking via `source_challenge_id` field
 - Unified JSON format with `entry_type` field (daily/weekly/challenge)
 
-**Access:** Footer navigation links at the bottom of the page
+**Access:** 'Leaderboard' link in the footer navigation at the bottom of the page
 
 ### Deployment & Technical
 - **Dockerfile-based deployment** supported for Hugging Face Spaces and other container platforms
@@ -237,7 +237,7 @@ All test files must be placed in the `/tests` folder. This ensures a clean proje
 4. Earn points for correct guesses and bonus points for unrevealed letters.
 5. **The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.**
 6. **To play a shared challenge, use a link with `?game_id=<sid>`. Your result will be added to the challenge leaderboard.**
-7. **Access leaderboards anytime using the footer navigation links at the bottom of the page.**
+7. **Access leaderboards anytime using the 'Leaderboard' link in the footer navigation.**
 
 ## Changelog
 
@@ -425,165 +425,4 @@ Ensure you have the necessary permissions and API access (if required) to use th
 
 For any issues or enhancements, please refer to the project documentation or contact the project maintainer.
 
-Happy gaming and sound designing!
-
-## What's New in v0.2.1: Daily & Weekly Leaderboards 🏆
-
-### Comprehensive Leaderboard System
-- **Settings-Based Competition:** Separate leaderboards for each unique settings combination
-  - Game mode (classic, easy, too easy)
-  - Wordlist source (classic.txt, fourth_grade.txt, etc.)
-  - Display options (show incorrect guesses, enable free letters)
-  - Puzzle options (spacer, may_overlap)
-- **Daily & Weekly Periods:** Top 20 scores per day and per ISO week
-- **Automatic Qualification:** Submit scores after any game completion
-- **Settings page planned:** Move from sidebar to dedicated page, login required
-
-### Leaderboard Page Navigation
-- **Today Tab:** Current daily and weekly leaderboards with direct link filtering
-- **Daily Tab:** Last 7 days of history with expandable date groups
-- **Weekly Tab:** Current week with all settings combinations
-- **History Tab:** Browse any past period with dropdown selectors
-
-### Storage & Discovery
-- **Folder-Based Architecture:** No index.json, scans period folders directly
-- **File ID Format:** `{wordlist_source}-{game_mode}-{sequence}` for fast filtering
-- **HuggingFace Storage:** `games/leaderboards/{daily|weekly}/{period}/{file_id}/settings.json`
-- **Unified Format:** Single JSON structure with `entry_type` field (daily/weekly/challenge)
-
-### Integration Features
-- Challenge scores automatically contribute to daily/weekly leaderboards
-- Source tracking via `source_challenge_id` field
-- Query parameters for direct leaderboard links
-- Settings badges display full game configuration
-
-### Challenge Mode 🎯 (Existing Features)
-- Share challenges with friends via short URLs (`?game_id=<sid>`)
-- Multi-user challenge leaderboards sorted by score and time
-- Top 5 players displayed in Challenge Mode banner
-- "Show Challenge Share Links" toggle for privacy control (default OFF)
-
-## Known Issues / TODO
-
-- Word list loading bug: the app may not select the proper word lists in some environments. Investigate `word_loader.get_wordlist_files()` / `load_word_list()` and sidebar selection persistence to ensure the chosen file is correctly used by the generator.
-
-## Development Phases
-
-- **Proof of Concept (0.1.0):** No overlaps, basic UI, single session.
-- **Beta (0.5.0):** Responsive layout, leaderboards, keyboard support, deterministic seed.
-- **Full (1.0.0):** Enhanced UX, Overlaps allowed on shared letters, persistence, daily/practice modes, advanced features.
-
-See `specs/requirements.md` and `specs/specs.md` for full details and roadmap.
-
-## License
-
-Wrdler is based on BattleWords. BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.
-
-## Hugging Face Spaces Configuration
-
-Wrdler is deployable as a Hugging Face Space. You can use either the YAML config block or a Dockerfile for advanced/custom deployments.
-
-To configure your Space with the YAML block, add it at the top of your `README.md`:
-
-```yaml
----
-title: Wrdler
-emoji: 🎲
-colorFrom: blue
-colorTo: indigo
-sdk: streamlit
-sdk_version: 1.51.0
-python_version: 3.12.8
-app_file: app.py
-tags:
- - game
- - vocabulary
- - streamlit
- - education
----
-```
-
-**Key parameters:**
-- `title`, `emoji`, `colorFrom`, `colorTo`: Visuals for your Space.
-- `sdk`: Use `streamlit` for Streamlit apps.
-- `sdk_version`: Latest supported Streamlit version.
-- `python_version`: Python version (default is3.10).
-- `app_file`: Entry point for your app.
-- `tags`: List of descriptive tags.
-
-**Dependencies:** 
-Add a `requirements.txt` with your Python dependencies (e.g., `streamlit`, etc.).
-
-**Port:** 
-Streamlit Spaces use port `8501` by default.
-
-**Embedding:**
-Spaces can be embedded in other sites using an `<iframe>`:
-
-```html
-<iframe src="https://[YourUsername]-Wrdler.hf.space?embed=true" title="Wrdler"></iframe>
-```
-
-For full configuration options, see [Spaces Config Reference](https://huggingface.co/docs/hub/spaces-config-reference) and [Streamlit SDK Guide](https://huggingface.co/docs/hub/spaces-sdks-streamlit).
-
-# Assets Setup
-
-To fully experience Wrdler, especially the audio elements, ensure you set up the following assets:
-
-- Place your background music `.mp3` files in `wrdler/assets/audio/music/` to enable music.
-- Place your sound effect files (`.mp3` or `.wav`) in `wrdler/assets/audio/effects/` for sound effects.
-
-Refer to the documentation for guidance on compatible audio formats and common troubleshooting tips.
-
-# Sound Asset Generation
-
-To generate and save custom sound effects for Wrdler, you can use the `generate_sound_effect` function.
-
-## Function: `generate_sound_effect`
-
-```python
-def generate_sound_effect(effect: str, save_to_assets: bool = False, use_api: str = "huggingface") -> str:
- """
- Generate a sound effect and save it as a file.
-
- Parameters:
- - `effect`: Name of the effect to generate.
- - `save_to_assets`: If `True`, saves the effect to the assets directory; 
- if `False`, saves to a temporary location. Default is `False`.
- - `use_api`: API to use for generation. Options are "huggingface" or "replicate". Default is "huggingface".
-
- Returns:
- - File path to the saved sound effect.
- ```
-
-## Parameters
-
-- `effect`: The name of the sound effect you want to generate (e.g., "explosion", "powerup").
-- `save_to_assets` (optional): Set to `True` to save the generated sound effect to the game's assets directory. If `False`, the effect is saved to a temporary location. Default is `False`.
-- `use_api` (optional): The API to use for generating the sound. Options are `"huggingface"` or `"replicate"`. Default is `"huggingface"`.
-
-## Returns
-
-- The function returns the file path to the saved sound effect, whether it's in the assets directory or a temporary location.
-
-## Usage Example
-
-To generate a sound effect and save it to the assets directory:
-
-```python
-generate_sound_effect("your_effect_name", save_to_assets=True)
-```
-
-To generate a sound effect and keep it in a temporary location:
-
-```python
-temp_path = generate_sound_effect("your_effect_name", save_to_assets=False)
-```
-
-## Note
-
-Ensure you have the necessary permissions and API access (if required) to use the sound generation service. Generated sounds are subject to the terms of use of the respective API.
-
-For any issues or enhancements, please refer to the project documentation or contact the project maintainer.
-
 Happy gaming and sound designing!

specs/leaderboard_spec.md

@@ -185,7 +185,7 @@ Instead of maintaining an `index.json` file, leaderboards are discovered by:
     ▼           ▼
 ┌───────┐ ┌───────────┐
 │ Daily │ │ Weekly    │
-│ LB    │ │ LB        │
+│ LB    │ │ LB        |
 └───────┘ └───────────┘
     │          │
     └────┬─────┘
@@ -745,7 +745,7 @@ HF_REPO_ID/games/
 
 #### Key Differences from Spec
 
-1. **Navigation:** Implemented as footer menu integration instead of sidebar button
+1. **Navigation:** Implemented as 'Leaderboard' link in the footer menu instead of sidebar button
 2. **Caching:** Not implemented in v0.2.0 (deferred to v0.3.0 for optimization)
 3. **Tab Implementation:** Used query parameters with custom nav links instead of Streamlit native tabs for better URL support
 4. **Table Rendering:** Used pandas DataFrames with styling instead of custom HTML tables
@@ -883,4 +883,4 @@ HF_REPO_ID/games/
   "YYYY-MM-DD HH:MM:SS PST to YYYY-MM-DD HH:MM:SS PST"
   (PST is UTC-8; adjust for daylight saving as needed)
   For example, a UTC file date of `2025-12-08` covers `2025-12-08 00:00:00 UTC` to `2025-12-08 23:59:59 UTC`, which is displayed as `2025-12-07 16:00:00 PST` to `2025-12-08 15:59:59 PST`.
-  The leaderboard expander label should show: `Monday, December 08, 2025 4:00 PM PST – Tuesday, December 09, 2025 3:59:59 PM PST [settings badge]`
+  The leaderboard expander label should show: `Mon, Dec 08, 2025 4:00 PM PST – Tue, Dec 09, 2025 3:59:59 PM PST [settings badge]`

specs/requirements.md

@@ -197,7 +197,9 @@ This document breaks down the implementation tasks for Wrdler using the game rul
   2025-12-08 00:00:00 UTC to 2025-12-08 23:59:59 UTC
   and
   2025-12-07 16:00:00 PST to 2025-12-08 15:59:59 PST
-  The leaderboard expander label should show: `Monday, December 08, 2025 4:00 PM PST – Tuesday, December 09, 2025 3:59:59 PM PST [settings badge]`
+  The leaderboard expander label should show: `Mon, Dec 08, 2025 4:00 PM PST – Tue, Dec 09, 2025 3:59:59 PM PST [settings badge]`
+
+**Access:** 'Leaderboard' link in the footer navigation at the bottom of the page
 
 ### Core Implementation
 
@@ -289,3 +291,6 @@ games/
 
 ## Test File Location
 All test files must be placed in the `/tests` folder. This ensures a clean project structure and makes it easy to discover and run all tests.
+
+### PWA Support
+- ✅ **PWA Installation:** App is installable as a Progressive Web App on desktop and mobile

specs/specs.md

@@ -138,6 +138,17 @@ HF_REPO_ID/games/
 - Filters by file_id prefix for matching settings
 - Loads and verifies full settings match
 
+**Date Display Updates:**
+- All leaderboard files use UTC for period boundaries.
+- When displaying daily leaderboards, show the UTC period as a PST date range.
+- Example: For UTC file date 2025-12-08, display:
+  2025-12-08 00:00:00 UTC to 2025-12-08 23:59:59 UTC
+  and
+  2025-12-07 16:00:00 PST to 2025-12-08 15:59:59 PST
+  The leaderboard expander label should show: `Mon, Dec 08, 2025 4:00 PM PST – Tue, Dec 09, 2025 3:59:59 PM PST [settings badge]`
+
+**Access:** 'Leaderboard' link in the footer navigation at the bottom of the page
+
 ### PWA Support
 - ✅ **PWA Installation:** App is installable as a Progressive Web App on desktop and mobile
   - Added `service worker` and `manifest.json`

wrdler/__init__.py

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

wrdler/leaderboard_page.py

@@ -5,12 +5,16 @@ Wrdler Leaderboard Page
 Streamlit page component for displaying daily and weekly leaderboards
 with historical lookup capabilities.
 """
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 import streamlit as st
-from datetime import datetime
+from datetime import datetime, timedelta, timezone
 from typing import Optional, Tuple
 import pandas as pd
+try:
+    from zoneinfo import ZoneInfo
+except ImportError:
+    ZoneInfo = None
 
 from wrdler.leaderboard import (
     load_leaderboard,
@@ -27,6 +31,40 @@ from wrdler.leaderboard import (
 from wrdler.modules.constants import APP_SETTINGS
 
 
+def _get_pst_range_str(date_id: str) -> str:
+    """
+    Convert UTC date string (YYYY-MM-DD) to a formatted PST date range string.
+    Example: "Mon, Dec 08, 2025 4:00 PM PST – Tue, Dec 09, 2025 3:59:59 PM PST"
+    """
+    try:
+        # UTC start and end
+        utc_start = datetime.strptime(date_id, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+        utc_end = utc_start + timedelta(days=1) - timedelta(seconds=1)
+        
+        tz = None
+        if ZoneInfo:
+            try:
+                tz = ZoneInfo("America/Los_Angeles")
+            except Exception:
+                pass
+        
+        if tz is None:
+            # Fallback to fixed offset UTC-8 (PST)
+            tz = timezone(timedelta(hours=-8), name="PST")
+            
+        pst_start = utc_start.astimezone(tz)
+        pst_end = utc_end.astimezone(tz)
+        
+        def fmt(dt, show_seconds=False):
+            # %I is 01-12. lstrip("0") removes leading zero.
+            time_str = dt.strftime("%I:%M" + (":%S" if show_seconds else "") + " %p").lstrip("0")
+            return f"{dt.strftime('%a, %b %d, %Y')} {time_str} {dt.strftime('%Z')}"
+
+        return f"{fmt(pst_start)} – {fmt(pst_end, show_seconds=True)}"
+    except Exception:
+        return date_id
+
+
 def _format_time(seconds: int) -> str:
     """Format seconds as MM:SS."""
     mins, secs = divmod(seconds, 60)
@@ -50,9 +88,9 @@ def _settings_badge(lb: LeaderboardSettings) -> str:
     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'}]"
+    #spacer = lb.puzzle_options.get("spacer", 0)
+    #overlap = lb.puzzle_options.get("may_overlap", False)
+    return f"\n\n[{mode} • {source} • {incorrect} • {free}]"
 
 
 def _render_leaderboard_table(leaderboard: Optional[LeaderboardSettings], title: str):
@@ -223,12 +261,8 @@ def _render_daily_tab():
 
     for date_id in daily_periods:
         # Human friendly date title
-        try:
-            date_obj = datetime.strptime(date_id, "%Y-%m-%d")
-            is_today = date_id == get_current_daily_id()
-            date_title = ("🌟 Today " if is_today else "") + date_obj.strftime("%A, %B %d, %Y")
-        except ValueError:
-            date_title = date_id
+        is_today = date_id == get_current_daily_id()
+        date_title = ("🌟 Today: " if is_today else "") + _get_pst_range_str(date_id)
 
         # List all settings folders (file_id) for this period
         settings_list = list_settings_for_period("daily", date_id)
@@ -313,7 +347,7 @@ def _render_history_tab():
 
                 if st.button("Load Daily", key="load_daily"):
                     leaderboard = load_leaderboard("daily", selected_daily, selected_file_id)
-                    header = f"Daily: {selected_daily} "
+                    header = f"Daily: {_get_pst_range_str(selected_daily)} "
                     if leaderboard is not None:
                         header += _settings_badge(leaderboard)
                     _render_leaderboard_table(leaderboard, header)
@@ -387,11 +421,7 @@ def _render_today_tab():
                 lb = load_leaderboard("daily", daily_id, gidd)
                 
                 if lb:
-                    try:
-                        date_obj = datetime.strptime(daily_id, "%Y-%m-%d")
-                        date_title = "🌟 Today " + date_obj.strftime("%A, %B %d, %Y")
-                    except ValueError:
-                        date_title = daily_id
+                    date_title = "🌟 Today: " + _get_pst_range_str(daily_id)
                     
                     header_suffix = _settings_badge(lb)
                     with st.expander(f"{date_title} {header_suffix}", expanded=True):
@@ -432,11 +462,7 @@ def _render_today_tab():
             st.subheader("📅 Daily")
             daily_id = get_current_daily_id()
             
-            try:
-                date_obj = datetime.strptime(daily_id, "%Y-%m-%d")
-                date_title = "Today " + date_obj.strftime("%A, %B %d, %Y")
-            except ValueError:
-                date_title = daily_id
+            date_title = "Today " + _get_pst_range_str(daily_id)
             
             settings_list = list_settings_for_period("daily", daily_id)
             if not settings_list:

wrdler/ui.py

@@ -1618,7 +1618,7 @@ def _render_guess_form(state: GameState):
             display: inline-flex;
             align-items: center;
             width: auto;
-            min-width: 100px;
+            min-width:  100px;
         }
         .st-key-guess_input .stTooltipIcon .stTooltipHoverTarget::after {
             content: "incorrect guesses";
@@ -2408,9 +2408,7 @@ def _render_footer(current_page: str = "play"):
     """
     # Determine which link should be highlighted as active
     play_active = "active" if current_page == "play" else ""
-    today_active = "active" if current_page == "today" else ""
-    daily_active = "active" if current_page == "daily" else ""
-    weekly_active = "active" if current_page == "weekly" else ""
+    leaderboard_active = "active" if current_page in {"today", "daily", "weekly", "history"} else ""
     
     # Check if we're in challenge mode and need to preserve game_id
     game_id = None
@@ -2430,11 +2428,13 @@ def _render_footer(current_page: str = "play"):
         today_url = f"?page=today&game_id={game_id}"
         daily_url = f"?page=daily&game_id={game_id}"
         weekly_url = f"?page=weekly&game_id={game_id}"
+        leaderboard_url = f"?page=today&game_id={game_id}"
         play_url = f"?game_id={game_id}"
     else:
         today_url = "?page=today"
         daily_url = "?page=daily"
         weekly_url = "?page=weekly"
+        leaderboard_url = "?page=today"
         play_url = "/"
     
     st.markdown(
@@ -2494,9 +2494,7 @@ def _render_footer(current_page: str = "play"):
         </style>
         <div class="bw-footer">
             <nav class="bw-footer-nav">
-                <a href="{today_url}" title="View Today's Leaderboards" target="_self" class="{today_active}">🌟 Today</a>
-                <a href="{daily_url}" title="View Daily Leaderboards" target="_self" class="{daily_active}">📅 Daily</a>
-                <a href="{weekly_url}" title="View Weekly Leaderboards" target="_self" class="{weekly_active}">📆 Weekly</a>
+                <a href="{leaderboard_url}" title="View Leaderboards" target="_self" class="{leaderboard_active}">🏆 Leaderboard</a>
                 <a href="{play_url}" title="Play Wrdler" target="_self" class="{play_active}">🎮 Play</a>
             </nav>
         </div>