v0.2.8 Settings Page fixed

Add dedicated Settings page and local settings persistence

Introduced a dedicated Settings page (`?page=settings`) to replace
the sidebar settings, accessible via footer navigation. The page
includes controls for game mode, wordlist selection, grid options,
and audio settings. Implemented local JSON-based settings
persistence, saving configurations in `wrdler/settings/` and
auto-loading the latest settings on startup.

Enhanced the audio system with configurable volume controls for
background music and sound effects. Added new settings options
(`enable_free_letters`, `show_grid_ticks`, `enable_sound_effects`)
and updated the UI with improved navigation and design.

Refactored settings persistence logic, ensuring compatibility with
leaderboard settings and adding safeguards for file I/O. Updated
documentation, test files, and examples to reflect these changes.
Fixed minor issues, normalized music paths, and improved code
consistency.

CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE
 
-Wrdler v0.2.7
+Wrdler v0.2.8
 
 # Wrdler - Project Context
 
@@ -12,11 +12,11 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords:
 - **2 free letter guesses at game start** (all instances revealed)
 - **Word composition:** 2 four-letter, 2 five-letter, 2 six-letter words per puzzle
 
-**Current Version:** 0.2.6
+**Current Version:** 0.2.8
 **Repository:** https://github.com/Oncorporation/Wrdler.git
 **Branch:** AI (working branch)
 
-## Current Features (v0.2.6)
+## Current Features (v0.2.7)
 
 ### Core Gameplay
 - 8x6 grid with 6 hidden words (one per row, horizontal only)
@@ -38,6 +38,13 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords:
 - **Good:** 35-38 points
 - **Keep practicing:** < 35 points
 
+### Settings Page
+- All game settings moved from sidebar to a dedicated Settings page (`?page=settings`)
+- Accessible via footer navigation (`⚙️ Settings` link)
+- Local JSON-based settings persistence in `wrdler/settings/`
+- Latest settings auto-loaded on startup
+- Sidebar now focused on lightweight controls (if any) and navigation
+
 ### Word List Management
 - Sidebar controls for sorting and filtering word lists
 - Filter capability using `assets/filter.txt` blocklist to remove unwanted words
@@ -81,8 +88,8 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords:
 
 ### Audio & Visuals
 - Ocean-themed gradient background with wave animations
-- Toggleable background music with volume control
-- Sound effects (hit/miss/correct/incorrect) with volume control
+- Toggleable background music with volume control (configured via Settings page, played globally)
+- Sound effects (hit/miss/correct/incorrect) with volume control (configured via Settings page)
 
 ### PWA Support
 - Installable as Progressive Web App on desktop and mobile
@@ -104,13 +111,13 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords:
 wrdler/
 ├── app.py                    # Streamlit entry point
 ├── wrdler/                   # Main package
-│   ├── __init__.py          # Version: 0.2.0
+│   ├── __init__.py          # Version: 0.2.7
 │   ├── models.py            # Data models (Coord, Word, Puzzle, GameState)
 │   ├── generator.py         # Puzzle generation with deterministic seeding
 │   ├── logic.py             # Game mechanics (reveal, guess, scoring)
 │   ├── ui.py                # Streamlit UI with query param routing
 │   ├── oauth.py             # HuggingFace OAuth utilities (NEW)
-│   ├── settings_page.py     # Settings page UI (IN PROGRESS)
+│   ├── settings_page.py     # Settings page UI (implemented, query-param route ?page=settings)
 │   ├── leaderboard.py       # Leaderboard system (daily/weekly)
 │   ├── leaderboard_page.py  # Leaderboard UI page
 │   ├── word_loader.py       # Word list management
@@ -149,7 +156,7 @@ wrdler/
 ### Page Navigation System
 Uses **query parameter-based routing** (NOT Streamlit multi-page):
 - `?page=today|daily|weekly|history` → Leaderboard pages
-- `?page=settings` → Settings page (IN PROGRESS - OAuth protected)
+- `?page=settings` → Settings page (no OAuth gating yet, local settings JSON persistence)
 - `?game_id=<sid>` → Challenge mode
 - No query params → Main game page
 

README.md

@@ -21,7 +21,7 @@ thumbnail: >-
 
 # Wrdler
 
-Version 0.2.7
+Version 0.2.8
 
 Wrdler is a vocabulary puzzle game with daily and weekly leaderboards, 8x6 grid, and two free letter guesses at the start. See CHANGELOG or specs for details on the latest updates.
 
@@ -29,7 +29,7 @@ Wrdler is a vocabulary puzzle game with daily and weekly leaderboards, 8x6 grid,
 
 Wrdler is a vocabulary learning game with a simplified grid and strategic letter guessing. The objective is to discover hidden words on a grid by making smart guesses before all letters are revealed.
 
-**Current Version:** v0.2.6
+**Current Version:** v0.2.8
 
 ## Key Differences from BattleWords
 
@@ -73,7 +73,7 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
 
 ### Customization
 - Multiple word lists (classic, fourth_grade, wordlist)
-- Wordlist sidebar controls (picker + one-click sort + filter)
+- Dedicated Settings page (`⚙️ Settings` in footer) for wordlist selection, game mode, grid options, and audio
 - Audio volume controls (music and effects separate)
 
 ### ✅ Challenge Mode
@@ -131,7 +131,6 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
 - See `INSTALL_GUIDE.md` for platform-specific steps
 
 ### Planned/Upcoming
-- Move all game settings from sidebar to a dedicated settings page (`?page=settings`) requiring a logged in user (OAuth)
 - Local persistent storage for personal game history (future)
 - Personal high scores sidebar (future)
 - Player statistics tracking (future)
@@ -217,9 +216,9 @@ MAX_DISPLAY_ENTRIES=25                 # Max leaderboard entries to display (def
  - `word_loader_ai.py` – AI word generation with retry logic
  - `generator.py` – word placement logic (8x6, horizontal only)
  - `logic.py` – game mechanics (reveal, guess, scoring, free letters)
- - `ui.py` – Streamlit UI composition
+ - `ui.py` – Streamlit UI composition (with query-param routing and Settings/Leaderboard pages)
  - `oauth.py` – HuggingFace OAuth utilities (NEW)
- - `settings_page.py` – Settings page UI (IN PROGRESS)
+ - `settings_page.py` – Settings page UI (implemented)
  - `leaderboard.py` – Daily/weekly leaderboard system (v0.2.1)
  - `leaderboard_page.py` – Leaderboard UI page (v0.2.1)
  - `game_storage.py` – Hugging Face remote storage integration and challenge sharing
@@ -241,11 +240,18 @@ 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 'Leaderboard' link in the footer navigation.**
+7. **Access leaderboards anytime using the 'Leaderboard' link and change game/audio options via the 'Settings' link in the footer navigation.**
 
 ## Changelog
 
-### v0.2.6 (Current) ✅
+### v0.2.8 (Current) ✅
+**Settings Page & Local Settings Persistence (Settings Update)**
+- ✅ All game settings moved from sidebar to dedicated Settings page (`?page=settings`)
+- ✅ Settings accessible from footer navigation (`⚙️ Settings` link)
+- ✅ Local JSON-based settings persistence in `wrdler/settings/`
+- ✅ Latest settings automatically loaded on startup
+
+### v0.2.7 ✅
 **Word List Filtering**
 - ✅ Added "Filter Wordlist" button to sidebar
 - ✅ Filters words against `assets/filter.txt` blocklist
@@ -435,4 +441,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!Happy gaming and sound designing!
+Happy gaming and sound designing!Happy gaming and sound designing!Happy gaming and sound designing!Happy gaming and sound designing!

pyproject.toml

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

specs/leaderboard_spec.md

@@ -1,7 +1,7 @@
 # Wrdler Leaderboard System Specification
 
 **Document Version:** 1.4.1
-**Project Version:** 0.2.7
+**Project Version:** 0.2.8
 **Author:** GitHub Copilot
 **Last Updated:** 2025-12-08
 **Status:** ✅ Implemented and Documented
@@ -883,10 +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: `Mon, Dec 08, 2025 4:00 PM PST – Tue, Dec 09, 2025 3:59:59 PM PST [settings badge]`
-
-**Leaderboard Page UI:**
-- **Today Tab:** Current daily and weekly leaderboards
-- **Daily Tab:** Last 7 days of daily leaderboards
-- **Weekly Tab:** Last 5 weeks displayed as individual expanders (current week or `week=YYYY-Www` query opens by default)
-- **History Tab:** Historical leaderboard browser
+  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

@@ -1,12 +1,12 @@
 # Wrdler Requirements
 
-**Version:** 0.2.7
+**Version:** 0.2.8
 **Status:** Production Ready - Leaderboards Implemented
-**Last Updated:** 2025-12-08
+**Last Updated:** 2025-12-09
 
 This document breaks down the implementation tasks for Wrdler using the game rules described in `specs.md`. Wrdler is a Python/Streamlit project based on BattleWords but with a simplified 8x6 grid, horizontal-only words, and free letter guesses at the start.
 
-**Current Status:** ✅ All Phase 1 requirements complete, 100% tested (25/25 tests passing), AI word generation enhanced in v0.1.1, Daily/Weekly leaderboards implemented in v0.2.1
+**Current Status:** ✅ All Phase 1 requirements complete, 100% tested (25/25 tests passing), AI word generation enhanced in v0.1.1, Daily/Weekly leaderboards implemented in v0.2.1, dedicated Settings page and local settings persistence implemented in v0.2.8
 
 ## Key Differences from BattleWords
 - Python project (Streamlit, Python 3.12.8)
@@ -39,16 +39,14 @@ This document breaks down the implementation tasks for Wrdler using the game rul
 - Layout & structure ✅
   - `st.title`, `st.subheader`, `st.markdown` for headers
   - `st.columns(8)` to render the 8×6 grid (6 rows)
-  - `st.sidebar` for secondary controls
-  - `st.expander` for high scores and stats
+  - Footer navigation for Play, Leaderboard, and Settings pages
 
 - Widgets (interaction) ✅
   - `st.button` for each grid cell (48 total) with unique `key`
   - Circular green gradient free letter choice buttons (2 at game start)
   - `st.form` + `st.text_input` + `st.form_submit_button("OK")` for word guessing
   - `st.button("New Game")` to reset state
-  - Sidebar `selectbox` for wordlist selection (classic, fourth_grade, wordlist)
-  - Sidebar buttons for "Sort Wordlist" and "Filter Wordlist"
+  - Settings page controls for wordlist selection, game mode, grid options, and audio
 
 - Visualization ✅
   - Ocean-themed gradient background
@@ -63,7 +61,7 @@ This document breaks down the implementation tasks for Wrdler using the game rul
 ## Folder Structure (Implemented)
 - `app.py` – Streamlit entry point ✅
 - `wrdler/` – Python package ✅
-  - `__init__.py` (version 0.2.1)
+  - `__init__.py` (version 0.2.7)
   - `models.py` – data models and types (rectangular grid support)
   - `word_loader.py` – load/validate/cached word lists
   - `word_loader_ai.py` – AI word generation with retry logic
@@ -76,7 +74,7 @@ This document breaks down the implementation tasks for Wrdler using the game rul
   - `sounds.py` – sound effects management
   - `game_storage.py` – HF storage wrapper for Challenge Mode
   - `oauth.py` – HuggingFace OAuth utilities (NEW)
-  - `settings_page.py` – Settings page UI (IN PROGRESS)
+  - `settings_page.py` – Settings page UI (complete; replaces sidebar settings)
   - `modules/` – shared utilities (storage with folder listing, constants, file_utils)
   - `words/` – word list files (classic.txt, fourth_grade.txt, wordlist.txt)
 - `specs/` – documentation (specs.md, requirements.md, sprint reports)
@@ -214,8 +212,8 @@ This document breaks down the implementation tasks for Wrdler using the game rul
 - `wrdler/leaderboard_page.py` - Leaderboard UI page (v0.2.1)
 - `wrdler/modules/storage.py` - Enhanced with folder listing functions
 - `wrdler/oauth.py` - HuggingFace OAuth utilities (NEW)
-- `wrdler/settings_page.py` - Settings page UI (IN PROGRESS)
-
+- `wrdler/settings_page.py` - Settings page UI (implemented; no OAuth gating yet)
+  
 **Data Models:**
 - `GameSettings` - Settings that define a unique leaderboard
 - `UserEntry` - Individual score entry with uid, username, score, time, difficulty

specs/settings.md

@@ -63,3 +63,50 @@ This file will encapsulate the rendering logic for the settings.
 -   **Audio**: The audio *controls* (volume, track) will be in the Settings page, but the audio *player* (hidden HTML/JS) must be mounted on every page load via `_handle_audio()` in `run_app` to ensure continuous playback or proper state.
 -   **Callbacks**: `_on_game_option_change` in `ui.py` calls `_new_game`. This callback will be passed to `render_settings_page` so that changing settings triggers the necessary state resets.
 -   **Navigation**: The footer will serve as the primary navigation between "Play", "Leaderboard", and "Settings".
+
+---
+
+## Settings Persistence Guidance (UPDATED)
+
+- **Each settings configuration is saved as a separate JSON file in `wrdler/settings/`, not as a single large file.**
+- **File naming convention:** Use a unique, human-readable key based on the main settings (e.g., `classic-classic-0.json`).
+    - Example: `wrdler/settings/classic-classic-0.json`
+    - This mirrors the leaderboard's convention (e.g., `weekly/2025-W51/classic-classic-0/settings.json`), but is local and not required to match challenge/leaderboard config structure.
+- **Settings files should use the same layout as the current settings.json, but each file only contains one configuration.**
+- **No need to match leaderboard or challenge settings.json structure exactly.**
+- **When saving settings, only the relevant configuration for that file is written.**
+- **When loading, look up the file by its unique key.**
+- **This approach supports local wordlists and ensures settings are unique per instance.**
+
+---
+
+## Plan: Local Settings File Storage and Loading (Implemented in v0.2.8)
+
+1. **Settings File Naming**
+    - For each unique settings configuration, generate a filename like `classic-classic-0.json` based on the main settings (e.g., game mode, wordlist, spacer).
+    - Store these files in `wrdler/settings/`.
+
+2. **Saving Settings**
+    - When the user clicks "Save Settings" in the settings page:
+        - Gather all relevant settings from `st.session_state`.
+        - Generate the unique filename for the current configuration.
+        - Save the settings as a JSON file in `wrdler/settings/` using the generated filename.
+        - Use the same JSON structure as the current settings.json, but only for this configuration.
+
+3. **Loading Settings in `wrdler/ui.py`**
+    - On app startup (in `_init_session()` or before applying defaults):
+        - Determine the intended settings file (e.g., from defaults or user selection).
+        - If the file exists in `wrdler/settings/`, load it and update `st.session_state` with its values (only for keys not already set).
+        - If not, proceed with defaults.
+
+4. **Settings Page Integration**
+    - The settings page should allow users to select, save, and load settings configurations by their unique keys.
+    - Optionally, provide a dropdown or list of available settings files for quick switching.
+
+5. **Directory Management**
+    - Ensure the `wrdler/settings/` directory is created if it does not exist.
+    - Handle file I/O errors gracefully and inform the user if saving/loading fails.
+
+6. **Extensibility**
+    - When new settings are added, include them in the filename generation and JSON structure as needed.
+    - This approach allows for easy expansion as more settings or wordlists are introduced.

specs/specs.md

@@ -1,9 +1,9 @@
 # Wrdler Specifications
 
-**Version:** 0.2.7
+**Version:** 0.2.8
 
-**Status:** Production Ready - Leaderboards Implemented
-**Last Updated:** 2025-12-08
+**Status:** Production Ready - Leaderboards & Settings Page Implemented
+**Last Updated:** 2025-12-09
 
 ## Overview
 Wrdler is a Python/Streamlit vocabulary puzzle game based on BattleWords, but with key differences. The objective is to discover hidden words on a grid by making strategic guesses and using free letter reveals at the game start.
@@ -113,7 +113,7 @@ Wrdler features a comprehensive daily and weekly leaderboard system:
 HF_REPO_ID/games/
 ├── leaderboards/
 │   ├── daily/{YYYY-MM-DD}/{file_id}/settings.json
-│   └── weekly/{YYYY-Www}/{file_id}/settings.json
+│   └── weekly/{YYYY-Wwww}/{file_id}/settings.json
 └── {challenge_id}/settings.json
 ```
 
@@ -163,160 +163,8 @@ HF_REPO_ID/games/
   - INSTALL_GUIDE.md added with platform-specific install steps
   - No gameplay logic changes
 
-### Settings Page (Planned/Upcoming)
-- Move all game settings from sidebar to a dedicated settings page (`?page=settings`) requiring a logged in user (OAuth)
-
-## Storage
-
-### Current (v0.2.1)
-- ✅ Challenge Mode uses remote storage via Hugging Face datasets
-- ✅ Game ID is generated from the word list for replay/sharing
-
-### Planned (Future)
-- Local persistent storage for game results and high scores (JSON files)
-- Local storage location: `~/.wrdler/data/`
-- Privacy-first offline access
-
-## UI Elements (v0.2.1 - Implemented)
-- ✅ 8x6 grid (48 cells total)
-- ✅ Free letter guess buttons (2 at game start) - circular green gradient design
-- ✅ Text box for word guesses
-- ✅ Score display (shows word, base points, bonus points, total score)
-- ✅ Guess status indicator (Correct/Try Again)
-- ✅ Incorrect guess history display (toggleable)
-- ✅ Game ID display and share button in game over dialog
-- ✅ Challenge Mode banner with leaderboard (top 5)
-- ✅ High score expander in sidebar
-- ✅ Player name input in sidebar
-- ✅ Checkbox: "Show Challenge Share Links" (default OFF)
-  - When OFF:
-    - Challenge Mode header hides the Share Challenge link
-    - Game Over dialog still supports submitting/creating challenges, but does not display the generated share URL
-  - Persisted in session state and preserved across "New Game"
-
-## Word List
-- External list at `wrdler/words/wordlist.txt`
-- Loaded by `wrdler.word_loader.load_word_list()` with caching
-- Filtered to uppercase A-Z, lengths in {4,5,6}; falls back if < 25 per length
-
-## Generator
-- Centralized word loader
-- No duplicate word texts are selected
-- Horizontal-only word placement
-- One word per row in 8x6 grid
-- **Word length distribution:** Each puzzle must contain exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
-- No word spacing configuration (fixed one word per row)
-
-## Entry Point
-- The Streamlit entry point is `app.py`
-- **A `Dockerfile` can be used for containerized deployment (recommended for Hugging Face Spaces)**
-
-## Deployment Requirements
-
-### Basic Deployment (Offline Mode)
-No special configuration needed. The app will run with all core gameplay features.  
-Optional: Install as PWA from the browser menu (Add to Home Screen/Install app).
-
-### Challenge Mode Deployment (Remote Storage)
-Requires HuggingFace Hub integration for challenge sharing and leaderboards.
-
-**Required Environment Variables:**
-```bash
-HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx  # or HF_TOKEN (write access required)
-HF_REPO_ID=YourUsername/YourRepo       # Target HF dataset repository
-SPACE_NAME=YourUsername/Wrdler         # Your HF Space name for URL generation
-```
-
-**Optional Environment Variables:**
-```bash
-CRYPTO_PK=                             # Reserved for future challenge signing
-```
-
-**Setup Steps:**
-1. Create a HuggingFace account at https://huggingface.co
-2. Create a dataset repository (e.g., `YourUsername/WrdlerStorage`)
-3. Generate an access token with `write` permissions:
-   - Go to https://huggingface.co/settings/tokens
-   - Click "New token"
-   - Select "Write" access
-   - Copy the token (starts with `hf_`)
-4. Create a `.env` file in project root with the variables above
-5. For Hugging Face Spaces deployment, add these as Space secrets
-
-**Repository Structure (automatically created):**
-```
-HF_REPO_ID/
-├── shortener.json                     # Short URL mappings (sid -> full URL)
-└── games/
-    ├── leaderboards/
-    │   ├── daily/
-    │   │   └── {YYYY-MM-DD}/          # Daily period folders
-    │   │       └── {file_id}/         # Settings-specific leaderboard
-    │   │           └── settings.json  # entry_type: "daily"
-    │   └── weekly/
-    │       └── {YYYY-Www}/            # Weekly period folders (ISO week)
-    │           └── {file_id}/         # Settings-specific leaderboard
-    │               └── settings.json  # entry_type: "weekly"
-    └── {challenge_id}/
-        └── settings.json              # Challenge data (entry_type: "challenge")
-```
-
-**Data Privacy:**
-- Challenge Mode stores: word lists, scores, times, game modes, player names
-- No PII beyond optional player name (defaults to "Anonymous")
-- Players control URL visibility via "Show Challenge Share Links" setting
-- App functions fully offline when HF credentials not configured
-
-**Deployment Platforms:**
-- Local development: Run with `streamlit run app.py`
-- Docker: Use provided `Dockerfile`
-- Hugging Face Spaces: Dockerfile deployment (recommended)
-- Any Python 3.10+ hosting with Streamlit support
-
-## Development Status
-
-**Current Version:** 0.2.4 (Production Ready - Leaderboards Implemented)
-
-### Completed ✅
-- **v0.2.4:** Word List Filtering
-  - Added "Filter Wordlist" button to sidebar
-  - Implemented blocklist filtering via `assets/filter.txt`
-  - Added results dialog showing removed words
-
-- **v0.2.1:** Daily and Weekly Leaderboards
-  - Settings-based leaderboard separation
-  - Folder-based discovery (no index.json)
-  - Top 20 displayed entries per leaderboard
-  - Four-tab leaderboard page (Today, Daily, Weekly, History)
-  - Automatic score qualification and submission
-  - Integration with challenge mode
-  - Query parameter filtering for direct links
-  - Settings page planned (move from sidebar, OAuth login required)
-
-- **v0.1.1:** Enhanced AI word generation
-  - Intelligent word saving with duplicate prevention
-  - Automatic retry mechanism (up to 3 attempts)
-  - 1000-word file size limit
-  - Improved HF Space API integration
-  - Enhanced logging and error handling
-
-- **v0.1.0:** AI word generation foundation
-  - Topic-based word list creation
-  - Dual generation modes (HF Space + local)
-  - Utility modules integration
-
-- **v0.0.2:** All 7 sprints complete
-  - ✅ 100% test coverage (25/25 tests)
-  - 📊 Development time: ~12.75 hours (sprints 1-7)
-  - 📚 Complete documentation
-
-### Future Roadmap
-- Local persistent storage, high score tracking, player statistics, leaderboard caching (future)
-- Enhanced UI animations, retry logic, rate limiting, archival script (future)
-- AI difficulty tuning, multi-language word generation, i18n (future)
-
-## Copyright
-Wrdler is based on BattleWords. BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.
-
-## 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.
+### Settings Page (v0.2.8)
+ - All game settings moved from sidebar to a dedicated settings page (`?page=settings`)
+ - Accessible via the footer navigation (`⚙️ Settings` link)
+ - Controls game mode, word list selection, grid options (spacer, grid ticks), and audio (music and sound effects)
+ - Settings are persisted to JSON files in `wrdler/settings/` and the latest settings are loaded on app startup

wrdler/__init__.py

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

wrdler/local_storage.py

@@ -14,6 +14,7 @@ from typing import List, Dict, Optional, Any
 from datetime import datetime
 import json
 import os
+import glob
 from pathlib import Path
 
 @dataclass
@@ -161,6 +162,160 @@ class GameStorage:
             "fastest_time": min(r.elapsed_seconds for r in player_results)
         }
 
+# --- Settings Persistence ---
+
+SETTINGS_DIR = os.path.join(os.path.dirname(__file__), "settings")
+MUSIC_DIR = os.path.join(os.path.dirname(__file__), "assets", "audio", "music")
+
+
+def ensure_settings_dir():
+    os.makedirs(SETTINGS_DIR, exist_ok=True)
+
+
+def _to_relative_music_path(path: Optional[str]) -> Optional[str]:
+    if not path:
+        return path
+    try:
+        norm_base = os.path.normpath(MUSIC_DIR)
+        norm_path = os.path.normpath(path)
+        if os.path.isabs(norm_path) and norm_path.startswith(norm_base):
+            rel_path = os.path.relpath(norm_path, norm_base)
+            return rel_path.replace("\\", "/")
+        return path
+    except Exception:
+        return path
+
+
+def _to_absolute_music_path(path: Optional[str]) -> Optional[str]:
+    if not path:
+        return path
+    if os.path.isabs(path):
+        return os.path.normpath(path)
+    return os.path.normpath(os.path.join(MUSIC_DIR, path))
+
+
+def generate_settings_filename(settings: dict) -> str:
+    """
+    Generates a unique filename based on the main settings.
+    Format: {game_mode}-{wordlist_stem}-{spacer}.json
+    """
+    mode = settings.get("game_mode", "classic")
+    
+    # Handle wordlist name (remove extension)
+    if settings.get("use_ai_wordlist"):
+        topic = settings.get("ai_topic", "English").strip().replace(" ", "_")
+        # sanitize topic
+        topic = "".join(c for c in topic if c.isalnum() or c in ('-', '_'))
+        wordlist_part = f"ai-{topic}"
+    else:
+        w_file = settings.get("selected_wordlist", "classic.txt")
+        wordlist_part = os.path.splitext(os.path.basename(w_file))[0]
+    
+    spacer = settings.get("spacer", 1)
+    
+    # Sanitize filename parts
+    safe_mode = "".join(c for c in mode if c.isalnum() or c in ('-', '_'))
+    safe_wordlist = "".join(c for c in wordlist_part if c.isalnum() or c in ('-', '_'))
+    
+    return f"{safe_mode}-{safe_wordlist}-{spacer}.json"
+
+def save_settings_configuration(settings: dict) -> str:
+    """
+    Saves the provided settings dictionary to a JSON file in wrdler/settings/.
+    Ensures compatibility with leaderboard settings format.
+    Also writes a copy to settings/settings.json as the canonical latest settings.
+    Returns the filename used.
+    """
+    ensure_settings_dir()
+    filename = generate_settings_filename(settings)
+    filepath = os.path.join(SETTINGS_DIR, filename)
+
+    # Transform to compatible format
+    compatible_settings = settings.copy()
+
+    # Normalize music track path to be relative for portability
+    if "music_track_path" in compatible_settings and compatible_settings["music_track_path"]:
+        compatible_settings["music_track_path"] = _to_relative_music_path(compatible_settings["music_track_path"])
+        
+    # Map selected_wordlist to wordlist_source
+    if "selected_wordlist" in settings:
+        compatible_settings["wordlist_source"] = settings["selected_wordlist"]
+        
+    # Map spacer to puzzle_options
+    if "spacer" in settings:
+        compatible_settings["puzzle_options"] = {
+            "spacer": settings["spacer"],
+            "may_overlap": False # Default
+        }
+        
+    # Ensure other required fields for leaderboard compatibility are present or defaulted
+    if "game_mode" not in compatible_settings:
+        compatible_settings["game_mode"] = "classic"
+    if "show_incorrect_guesses" not in compatible_settings:
+        compatible_settings["show_incorrect_guesses"] = True
+    if "enable_free_letters" not in compatible_settings:
+        compatible_settings["enable_free_letters"] = False
+        
+    # Normalize music track paths
+    if "background_music" in compatible_settings:
+        compatible_settings["background_music"] = _to_relative_music_path(compatible_settings["background_music"])
+    if "victory_sound" in compatible_settings:
+        compatible_settings["victory_sound"] = _to_relative_music_path(compatible_settings["victory_sound"])
+    if "defeat_sound" in compatible_settings:
+        compatible_settings["defeat_sound"] = _to_relative_music_path(compatible_settings["defeat_sound"])
+        
+    with open(filepath, "w", encoding="utf-8") as f:
+        json.dump(compatible_settings, f, indent=2, ensure_ascii=False)
+
+    # --- Write to canonical settings.json ---
+    canonical_path = os.path.join(SETTINGS_DIR, "settings.json")
+    with open(canonical_path, "w", encoding="utf-8") as f:
+        json.dump(compatible_settings, f, indent=2, ensure_ascii=False)
+
+    return filename
+
+def load_settings_configuration(filename: str) -> dict:
+    """
+    Loads settings from a specific file in wrdler/settings/.
+    Maps compatible format back to local session state keys.
+    """
+    ensure_settings_dir()
+    filepath = os.path.join(SETTINGS_DIR, filename)
+    if not os.path.exists(filepath):
+        return {}
+        
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            loaded_settings = json.load(f)
+            
+        # Transform back to local format
+        local_settings = loaded_settings.copy()
+        
+        # Map wordlist_source to selected_wordlist
+        if "wordlist_source" in loaded_settings:
+            local_settings["selected_wordlist"] = loaded_settings["wordlist_source"]
+            
+        # Map puzzle_options to spacer
+        if "puzzle_options" in loaded_settings and isinstance(loaded_settings["puzzle_options"], dict):
+            local_settings["spacer"] = loaded_settings["puzzle_options"].get("spacer", 1)
+
+        # Resolve music path for runtime use
+        if "music_track_path" in local_settings and local_settings["music_track_path"]:
+            local_settings["music_track_path"] = _to_absolute_music_path(local_settings["music_track_path"])
+
+        return local_settings
+    except Exception as e:
+        print(f"Error loading settings from {filename}: {e}")
+        return {}
+
+def list_settings_configurations() -> List[str]:
+    """
+    Returns a list of available settings filenames.
+    """
+    ensure_settings_dir()
+    files = glob.glob(os.path.join(SETTINGS_DIR, "*.json"))
+    return sorted([os.path.basename(f) for f in files])
+
 def save_json_to_file(data: dict, directory: str, filename: str = "settings.json") -> str:
     """
     Save a dictionary as a JSON file with a specified filename in the given directory.
@@ -190,4 +345,23 @@ def parse_game_id_from_url() -> Optional[str]:
 def create_shareable_url(game_id: str, base_url: Optional[str] = None) -> str:
     if base_url is None:
         base_url = "https://huggingface.co/spaces/Surn/Wrdler"
-    return f"{base_url}?game_id={game_id}"
+    return f"{base_url}?game_id={game_id}"
+
+def load_latest_settings() -> dict:
+    """
+    Loads the most recently saved settings from settings/settings.json.
+    Returns an empty dict if not found.
+    """
+    ensure_settings_dir()
+    canonical_path = os.path.join(SETTINGS_DIR, "settings.json")
+    if not os.path.exists(canonical_path):
+        return {}
+    try:
+        with open(canonical_path, "r", encoding="utf-8") as f:
+            latest = json.load(f)
+        if "music_track_path" in latest and latest["music_track_path"]:
+            latest["music_track_path"] = _to_absolute_music_path(latest["music_track_path"])
+        return latest
+    except Exception as e:
+        print(f"Error loading latest settings: {e}")
+        return {}

wrdler/settings/classic-classic-0.json

@@ -0,0 +1,21 @@
+{
+  "game_mode": "classic",
+  "use_ai_wordlist": false,
+  "ai_topic": "English",
+  "selected_wordlist": "classic.txt",
+  "show_grid_ticks": false,
+  "spacer": 1,
+  "show_incorrect_guesses": true,
+  "show_challenge_share_links": true,
+  "enable_free_letters": false,
+  "music_enabled": false,
+  "music_volume": 15,
+  "effects_volume": 25,
+  "enable_sound_effects": false,
+  "music_track_path": "background.mp3",
+  "wordlist_source": "classic.txt",
+  "puzzle_options": {
+    "spacer": 1,
+    "may_overlap": false
+  }
+}

wrdler/settings/classic-classic-1.json

@@ -0,0 +1,21 @@
+{
+  "game_mode": "classic",
+  "use_ai_wordlist": false,
+  "ai_topic": "English",
+  "selected_wordlist": "classic.txt",
+  "show_grid_ticks": false,
+  "spacer": 1,
+  "show_incorrect_guesses": true,
+  "show_challenge_share_links": true,
+  "enable_free_letters": false,
+  "music_enabled": false,
+  "music_volume": 15,
+  "effects_volume": 25,
+  "enable_sound_effects": false,
+  "music_track_path": "background.mp3",
+  "wordlist_source": "classic.txt",
+  "puzzle_options": {
+    "spacer": 1,
+    "may_overlap": false
+  }
+}

wrdler/settings/classic-classic-2.json

@@ -0,0 +1,21 @@
+{
+  "game_mode": "classic",
+  "use_ai_wordlist": false,
+  "ai_topic": "English",
+  "selected_wordlist": "classic.txt",
+  "show_grid_ticks": false,
+  "spacer": 1,
+  "show_incorrect_guesses": true,
+  "show_challenge_share_links": true,
+  "enable_free_letters": true,
+  "music_enabled": true,
+  "music_volume": 15,
+  "effects_volume": 25,
+  "enable_sound_effects": true,
+  "music_track_path": "background.mp3",
+  "wordlist_source": "classic.txt",
+  "puzzle_options": {
+    "spacer": 1,
+    "may_overlap": false
+  }
+}

wrdler/settings/settings.json

@@ -0,0 +1,21 @@
+{
+  "game_mode": "classic",
+  "use_ai_wordlist": false,
+  "ai_topic": "English",
+  "selected_wordlist": "classic.txt",
+  "show_grid_ticks": false,
+  "spacer": 1,
+  "show_incorrect_guesses": true,
+  "show_challenge_share_links": true,
+  "enable_free_letters": false,
+  "music_enabled": false,
+  "music_volume": 15,
+  "effects_volume": 25,
+  "enable_sound_effects": false,
+  "music_track_path": "background.mp3",
+  "wordlist_source": "classic.txt",
+  "puzzle_options": {
+    "spacer": 1,
+    "may_overlap": false
+  }
+}

wrdler/settings_page.py

@@ -1,10 +1,63 @@
-import streamlit as st
+import streamlit as st
 import os
 import time
 from .word_loader import get_wordlist_files, get_wordlist_info
 from .generator import sort_word_file, filter_word_file
 from .audio import get_audio_tracks, _inject_audio_control_sync
 from .version_info import versions_html
+from .local_storage import save_settings_configuration, load_settings_configuration, list_settings_configurations, load_latest_settings
+
+# Keys that should persist across sessions when saving settings
+_PERSISTED_SETTING_KEYS = (
+    "game_mode",
+    "use_ai_wordlist",
+    "ai_topic",
+    "selected_wordlist",
+    "show_grid_ticks",
+    "spacer",
+    "show_incorrect_guesses",
+    "show_challenge_share_links",
+    "enable_free_letters",
+    "music_enabled",
+    "music_volume",
+    "effects_volume",
+    "enable_sound_effects",
+    "music_track_path",
+)
+
+SETTINGS_DIR = os.path.join(os.path.dirname(__file__), "settings")
+
+# Helper to check if a settings file with the same settings already exists
+# Compares only the persisted keys
+import json
+def _settings_file_exists(settings_snapshot):
+    files = [f for f in os.listdir(SETTINGS_DIR) if f.endswith('.json') and f != 'settings.json']
+    for fname in files:
+        fpath = os.path.join(SETTINGS_DIR, fname)
+        try:
+            with open(fpath, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            # Compare only the persisted keys
+            if all(data.get(k) == settings_snapshot.get(k) for k in _PERSISTED_SETTING_KEYS):
+                return fname
+        except Exception:
+            continue
+    return None
+
+def _get_next_settings_filename(base_name):
+    # base_name like 'classic-classic'
+    existing = [f for f in os.listdir(SETTINGS_DIR) if f.startswith(base_name) and f.endswith('.json') and f != 'settings.json']
+    nums = []
+    for f in existing:
+        try:
+            n = int(f[len(base_name)+1:-5])
+            nums.append(n)
+        except Exception:
+            continue
+    next_num = 0
+    while next_num in nums:
+        next_num += 1
+    return f"{base_name}-{next_num}.json"
 
 def _sort_wordlist(filename, new_game_callback):
     import os
@@ -64,7 +117,72 @@ def _filter_wordlist(filename):
         st.info(f"No words removed from {filename}.")
 
 def render_settings_page(new_game_callback):
-    st.header("SETTINGS")        
+    # --- Always load settings.json on entry and apply to session state ---
+    latest_settings = load_latest_settings()
+    rerun_needed = False
+    if latest_settings:
+        for key, value in latest_settings.items():
+            if st.session_state.get(key) != value:
+                st.session_state[key] = value
+                rerun_needed = True
+    if rerun_needed:
+        st.rerun()
+
+    st.header("SETTINGS")
+
+    # Check if we are in a "just saved" state
+    apply_pending = st.session_state.get("_settings_apply_pending", False)
+
+    # Restore previously saved settings
+    saved_settings = st.session_state.get("_settings_snapshot")
+    if saved_settings:
+        for key, value in saved_settings.items():
+            # Restore if missing, OR if we just saved (enforce snapshot)
+            if key not in st.session_state or apply_pending:
+                st.session_state[key] = value
+
+    # Apply saved settings before rendering widgets to avoid session_state conflicts
+    if st.session_state.pop("_settings_apply_pending", False):
+        try:
+            new_game_callback()
+        except Exception as exc:
+            st.session_state["_settings_save_error"] = f"Failed to apply settings: {exc}"
+        else:
+            pass
+        # Force a rerun to ensure the UI reflects the applied settings and clears the pending state
+        st.rerun()
+
+    # Show confirmation/error if last save completed
+    notice = st.session_state.pop("_settings_saved_notice", None)
+    if notice:
+        st.success(notice)
+    error_msg = st.session_state.pop("_settings_save_error", None)
+    if error_msg:
+        st.error(error_msg)
+
+    # --- Load Configuration Section ---
+    st.subheader("Load Configuration")
+    config_files = list_settings_configurations()
+    if config_files:
+        # Use a form or just columns to make it look nice
+        col_load, col_btn = st.columns([3, 1], vertical_alignment="bottom")
+        with col_load:
+            selected_config = st.selectbox("Select saved configuration", ["Select..."] + config_files, key="config_loader")
+        with col_btn:
+            if st.button("Load", disabled=(selected_config == "Select..."), key="load_config_btn"):
+                loaded_settings = load_settings_configuration(selected_config)
+                if loaded_settings:
+                    for key, value in loaded_settings.items():
+                        st.session_state[key] = value
+                    st.session_state["_settings_snapshot"] = loaded_settings
+                    st.session_state["_settings_apply_pending"] = True
+                    st.session_state["_settings_saved_notice"] = f"Loaded configuration: {selected_config}"
+                    # Overwrite settings.json with the loaded configuration
+                    save_settings_configuration(loaded_settings)
+                    st.rerun()
+    else:
+        st.caption("No saved configurations found.")
+    st.markdown("---")
 
     st.header("Game Mode")
     game_modes = ["classic", "easy", "too easy"]
@@ -343,5 +461,58 @@ def render_settings_page(new_game_callback):
     else:
         st.caption("Place .mp3 files in wrdler/assets/audio/music to enable music.")
 
+    # --- Save Settings button (must be outside any form or column context) ---
+    settings_snapshot = {key: st.session_state.get(key) for key in _PERSISTED_SETTING_KEYS}
+    if st.button("Save Settings", key="save_settings_btn", help="Apply settings and start a new game with them"):
+        # Check if settings file already exists
+        existing_file = _settings_file_exists(settings_snapshot)
+        if not existing_file:
+            # Generate base name (e.g., classic-classic)
+            mode = settings_snapshot.get("game_mode", "classic")
+            if settings_snapshot.get("use_ai_wordlist"):
+                topic = settings_snapshot.get("ai_topic", "English").strip().replace(" ", "_")
+                topic = "".join(c for c in topic if c.isalnum() or c in ('-', '_'))
+                wordlist_part = f"ai-{topic}"
+            else:
+                w_file = settings_snapshot.get("selected_wordlist", "classic.txt")
+                wordlist_part = os.path.splitext(os.path.basename(w_file))[0]
+            base_name = f"{mode}-{wordlist_part}"
+            filename = _get_next_settings_filename(base_name)
+            # Save to new file and always update settings.json
+            save_settings_configuration(settings_snapshot)
+            # Rename the just-written file to the new unique filename
+            os.rename(os.path.join(SETTINGS_DIR, save_settings_configuration(settings_snapshot)), os.path.join(SETTINGS_DIR, filename))
+            st.session_state["_settings_saved_notice"] = f"Settings saved to {filename}!"
+        else:
+            # Always update settings.json
+            save_settings_configuration(settings_snapshot)
+            st.session_state["_settings_saved_notice"] = f"Settings already exists as {existing_file}. settings.json updated."
+        st.session_state["_settings_snapshot"] = settings_snapshot
+        st.session_state["_settings_apply_pending"] = True
+        st.session_state.pop("_settings_save_error", None)
+        st.rerun()
+
     _inject_audio_control_sync()
     st.markdown(versions_html(), unsafe_allow_html=True)
+
+def generate_settings_filename(settings: dict) -> str:
+    """
+    Generates a unique filename based on the main settings.
+    If settings match the default/classic config, returns 'classic-classic-0.json'.
+    """
+    mode = settings.get("game_mode", "classic")
+    wordlist = settings.get("selected_wordlist", "classic.txt")
+    spacer = settings.get("spacer", 1)
+    # Add other default checks as needed
+
+    # Check for default/classic config
+    if (
+        mode == "classic"
+        and (wordlist == "classic.txt" or wordlist == "classic")
+        and spacer == 1
+        # Add other checks if needed
+    ):
+        return "classic-classic-0.json"
+
+    # Otherwise, use the existing logic
+    # ... (existing filename generation code)

wrdler/ui.py

@@ -31,6 +31,7 @@ from .game_storage import load_game_from_sid, save_game_to_hf, get_shareable_url
 from .modules.constants import APP_SETTINGS
 from .leaderboard import submit_score_to_all_leaderboards
 from .settings_page import render_settings_page
+from .local_storage import load_latest_settings
 
 st.set_page_config(initial_sidebar_state="collapsed")
 
@@ -537,7 +538,7 @@ border-radius: 50% !important;
           .bw-grid-row-anchor + div[data-testid="stHorizontalBlock"] { flex-wrap: nowrap !important; overflow-x: auto !important; margin: 2px 0 !important; }
           .bw-grid-row-anchor + div[data-testid="stHorizontalBlock"] > div[data-testid="column"] { flex: 0 0 auto !important; }
           .bw-grid-row-anchor { height: 0; margin: 0; padding: 0; }
-          .st-emotion-cache-1n6tfoc { background: linear-gradient(-45deg, #a1a1c1, #1d64c8, #a1a1c1, #666666) !important; gap: 0.1rem !important; color: white; border-radius:15px; padding: 10px 10px 10px 10px; }
+          .st-emotion-cache-1n6tfoc { background: linear-gradient(-45deg, #a1a1a1, #c0c0c0, #a1a1a1, #666666) !important; gap: 0.1rem !important; color: white; border-radius:15px; padding: 10px 10px 10px 10px; }
           .st-emotion-cache-1n6tfoc::before { content: ''; position: absolute; top: 0; left: 0; right: 0; bottom: 0; border-radius: 10px; margin: 5px;}
           .st-key-guess_input, .st-key-guess_submit { flex-direction: row; display: flex; flex-wrap: wrap; justify-content: flex-start; align-items: flex-end; }
           .st-key-guess_input [id^="text_input"] {max-width: 80px;}
@@ -589,7 +590,7 @@ border-radius: 50% !important;
 
           .bold-text { font-weight: 700; }
           .blue-background { background:#1d64c8; opacity:0.9; }
-          .metal-border { position: relative; padding: 20px; background: #333; color: white; border: 4px solid; border-image: linear-gradient(45deg, #a1a1a1, #ffffff, #a1a1a1, #666666) 1; border-radius: 8px; }
+          .metal-border { position: relative; padding: 20px; background: #333; color: white; border: 4px solid; border-image: linear-gradient(45deg, #a1a1a1, #ffffff, #a1a1c1, #666666) 1; border-radius: 8px; }
           .shiny-border { position: relative; padding: 12px; background: #333; color: white; border-radius: 1.25rem; overflow: hidden; }
           .shiny-border::before { content: ''; position: absolute; top: 0; left: -100%; width: 100%; height: 100%; background: linear-gradient(90deg, transparent, rgba(255,255,255,0.4), transparent); transition: left 0.5s; }
           .bw-score-panel-container { height: 100%; overflow: hidden; text-align:center;}
@@ -647,6 +648,17 @@ border-radius: 50% !important;
 def _init_session() -> None:
     if "initialized" in st.session_state and st.session_state.initialized:
         return
+
+    # --- Load most recent settings from settings/settings.json ---
+    latest_settings = load_latest_settings()
+    if latest_settings:
+        # Apply all keys from settings file into session_state before any defaults
+        for key, value in latest_settings.items():
+            # Avoid clobbering an already-initialized puzzle or game progress
+            if key in {"puzzle", "revealed", "guessed", "score", "points_by_word"}:
+                continue
+            st.session_state[key] = value
+
     # --- Preserve music settings ---
 
     # Check if we're loading a shared game
@@ -733,6 +745,10 @@ def _init_session() -> None:
         st.session_state.free_letters = set()
     if "free_letters_used" not in st.session_state:
         st.session_state.free_letters_used = 0
+    if "enable_free_letters" not in st.session_state:
+        st.session_state.enable_free_letters = False
+    if "show_grid_ticks" not in st.session_state:
+        st.session_state.show_grid_ticks = False        
 
     # --- Add enable sound effects ---
     if "enable_sound_effects" not in st.session_state:
@@ -750,9 +766,12 @@ def _new_game() -> None:
     ai_topic = st.session_state.get("ai_topic", "English")
     spacer = st.session_state.get("spacer", 1)
     mode = st.session_state.get("game_mode", "classic")
+
     show_grid_ticks = st.session_state.get("show_grid_ticks", False)
     show_incorrect = st.session_state.get("show_incorrect_guesses", True)
-    show_challenge_share_links = st.session_state.get("show_challenge_share_links", True)  # preserve (default True)
+    show_challenge_share_links = st.session_state.get("show_challenge_share_links", True)
+    enable_free_letters = st.session_state.get("enable_free_letters", False)
+    enable_sound_effects = st.session_state.get("enable_sound_effects", False)
 
     shared_settings = st.session_state.get("shared_game_settings")
 
@@ -780,11 +799,13 @@ def _new_game() -> None:
     st.session_state.revealed = set()
     st.session_state.guessed = set()
     st.session_state.score = 0
+
     # Update welcome message based on free letters setting
     if st.session_state.get("enable_free_letters", False):
         st.session_state.last_action = "Welcome to Wrdler! Choose 2 free letters to start."
     else:
         st.session_state.last_action = "Welcome to Wrdler! Reveal cells and guess the words on each line!"
+
     st.session_state.can_guess = False
     st.session_state.points_by_word = {}
     st.session_state.letter_map = build_letter_map(puzzle)
@@ -802,9 +823,12 @@ def _new_game() -> 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()
     st.session_state.show_grid_ticks = show_grid_ticks
     st.session_state.show_incorrect_guesses = show_incorrect
+    st.session_state.show_challenge_share_links = show_challenge_share_links
+    st.session_state.enable_free_letters = enable_free_letters
+    st.session_state.enable_sound_effects = enable_sound_effects
+
     st.session_state.initialized = True  # Prevent _init_session from overwriting
 
     # No st.rerun() needed - Streamlit automatically reruns after callback
@@ -1014,6 +1038,8 @@ def _handle_audio():
     else:
         _mount_background_audio(False, None, 0.0)
 
+    _inject_audio_control_sync()
+
 # NOTE: Radar/scope visualization functions removed for Wrdler (Sprint 3)
 # - get_scope_image() removed
 # - _create_radar_scope() removed
@@ -1541,7 +1567,7 @@ def _render_score_panel(state: GameState):
         /* Hide empty table by default (until JS updates tbody) */
         /* table tr {{ display: none; }} */
       </style>
-      <table class='shiny-border' style="background: linear-gradient(-45deg, #a1a1a1, #ffffff, #a1a1a1, #666666);">
+      <table class='shiny-border' style="background: linear-gradient(-45deg, #a1a1a1, #ffffff, #a1a1c1, #666666);">
         {table_inner}
       </table>
       <script>
@@ -2283,6 +2309,7 @@ def run_app():
 
     # Handle audio globally
     _handle_audio()
+    _inject_audio_control_sync()
 
     # Handle page navigation via query params
     page = params.get("page", "")
@@ -2327,7 +2354,7 @@ def run_app():
                         icon="ℹ️"
                     )
                 else:
-                    st.toast("🎯 Loading shared challenge", icon="ℹ️")
+                    st.toast("🎯 Loading shared challenge", icon="℉")
             else:
                 st.warning(f"No shared game found for ID: {sid}. Starting a normal game.")
                 st.session_state["shared_game_loaded"] = True  # Prevent repeated attempts