Version 0.2.31: UI/UX, settings, and audio updates

- Updated README.md with new Streamlit SDK (1.52.1) and Python (3.12.8).
- Incremented version to 0.2.31 in `__init__.py` and `pyproject.toml`.
- Enhanced `audio.py` with error handling and smoother playback.
- Added `validate_puzzle` and `filter_word_file` functions in `generator.py`.
- Introduced new constants and `load_settings` in `constants.py`.
- Improved settings page with wordlist controls and audio settings.
- Refined UI in `ui.py` with compact layouts and performance optimizations.
- Modularized helpers in `ui_helpers.py` and reintroduced PWA support.
- Updated wordlist in `classic.txt` with the addition of "CLUB".
- Revised documentation in `claude.md` for version 0.2.31.
- Added a new task in `upgrade.md` to remove animated backgrounds.

README.md

@@ -4,7 +4,7 @@ emoji: 🎲
 colorFrom: blue
 colorTo: indigo
 sdk: streamlit
-sdk_version: 1.51.0
+sdk_version: 1.52.1
 python_version: 3.12.8
 app_port: 8501
 app_file: app.py
@@ -19,6 +19,9 @@ tags:
 
 > **This project is used by [huggingface.co](https://huggingface.co/spaces/Surn/BattleWords) as a demonstration of interactive word games in Python.**
 
+**Current Version:** 0.2.31
+**Last Updated:** 2026-01-13
+
 BattleWords is a vocabulary learning game inspired by classic Battleship mechanics. The objective is to discover hidden words on a grid, earning points for strategic guessing before all letters are revealed.
 
 ## Current Upgrades (Wrdler Improvements)
@@ -66,12 +69,24 @@ The following non-gameplay improvements from Wrdler are being ported to BattleWo
 
 ### Version & Diagnostics
 - ✅ Ported version_info.py to modules
-- ⏳ Footer snippet: app version, git commit, python, streamlit
+- ✅ Footer snippet: app version, git commit, python, streamlit
 
 ### Dependency/Workflow Alignment
 - ⏳ Validate Streamlit version for st.query_params
 - ⏳ Align Python/Streamlit pins if needed
 
+---
+
+## Summary of Recent Changes (v0.2.31)
+- Updated README.md with new Streamlit SDK (1.52.1) and Python (3.12.8).
+- Incremented version to 0.2.31 in `__init__.py` and `pyproject.toml`.
+- Enhanced `audio.py` with error handling and smoother playback.
+- Added `validate_puzzle` and `filter_word_file` functions in `generator.py`.
+- Introduced new constants and `load_settings` in `constants.py`.
+- Improved settings page with wordlist controls and audio settings.
+- Refined UI in `ui.py` with compact layouts and performance optimizations.
+- Modularized helpers in `ui_helpers.py` and reintroduced PWA support.
+
 ## Features
 
 ### Core Gameplay
@@ -244,6 +259,16 @@ CRYPTO_PK=                             # Reserved for future signing
  - Personal high scores sidebar with filtering
  - Player statistics tracking (games played, averages, bests)
 
+-0.2.31
+ - Updated README.md with new Streamlit SDK (1.52.1) and Python (3.12.8).
+ - Incremented version to 0.2.31 in `__init__.py` and `pyproject.toml`.
+ - Enhanced `audio.py` with error handling and smoother playback.
+ - Added `validate_puzzle` and `filter_word_file` functions in `generator.py`.
+ - Introduced new constants and `load_settings` in `constants.py`.
+ - Improved settings page with wordlist controls and audio settings.
+ - Refined UI in `ui.py` with compact layouts and performance optimizations.
+ - Modularized helpers in `ui_helpers.py` and reintroduced PWA support.
+
 -0.2.29
  - change difficulty calculation 
  - add test_compare_difficulty_functions
@@ -527,28 +552,7 @@ def generate_sound_effect(effect: str, save_to_assets: bool = False, use_api: st
 
  Returns:
  - File path to the saved sound effect.
- """
-
- # ... [sound generation code] ...
-
- if save_to_assets:
- # Save to effects directory
- assets_dir = os.path.join(os.path.dirname(__file__), "assets", "audio", "effects")
- os.makedirs(assets_dir, exist_ok=True)
- filename = f"{effect}.wav"
- path = os.path.join(assets_dir, filename)
- with open(path, "wb") as f:
- f.write(audio_bytes)
- print(f" Saved to: {path}")
- else:
- # Save to temporary file
- with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmpfile:
- tmpfile.write(audio_bytes)
- path = tmpfile.name
- print(f" Saved to: {path}")
-
- return path
-```
+ ```
 
 ## Parameters
 

battlewords/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "0.2.30"
+__version__ = "0.2.31"
 __all__ = ["models", "generator", "logic", "ui", "game_storage", "modules"]

battlewords/audio.py

@@ -1,6 +1,7 @@
 import os
 from typing import Optional
 import streamlit as st
+import time
 
 def _get_music_dir() -> str:
     return os.path.join(os.path.dirname(__file__), "assets", "audio", "music")
@@ -207,6 +208,7 @@ def play_sound_effect(effect_name: str, volume: float = 0.5) -> None:
     # Respect Enable Sound Effects setting from sidebar
     try:
         if not st.session_state.get("enable_sound_effects", True):
+            # print(f"[DEBUG] Sound effects disabled; skipping sound effect '{effect_name}'.")
             return
     except Exception:
         pass
@@ -214,10 +216,15 @@ def play_sound_effect(effect_name: str, volume: float = 0.5) -> None:
     sound_files = get_sound_effect_files()
 
     if effect_name not in sound_files:
+        print(f"[DEBUG] Sound effect '{effect_name}' not found in available sound files.")
         return  # Sound file doesn't exist, silently skip
 
     sound_path = sound_files[effect_name]
-    sound_data_url = _load_audio_data_url(sound_path)
+    try:
+        sound_data_url = _load_audio_data_url(sound_path)
+    except Exception as e:
+        print(f"[DEBUG] Failed to load audio data for '{effect_name}' at '{sound_path}': {e}")
+        return
 
     # Clamp volume
     vol = max(0.0, min(1.0, float(volume)))
@@ -243,4 +250,5 @@ def play_sound_effect(effect_name: str, volume: float = 0.5) -> None:
         </script>
         """,
         height=0,
-    )
+    )
+    time.sleep(0.1)

battlewords/generator.py

@@ -173,11 +173,21 @@ def generate_puzzle(
             spacer=spacer,
             puzzle_id=puzzle_id,
             _retry=_retry + 1,
+            target_words=target_words,
         )
     return puzzle
 
 
 def validate_puzzle(puzzle: Puzzle, grid_size: int = 12) -> None:
+    """
+    Validate Wrdler puzzle constraints.
+
+    Checks:
+    1. Exactly 6 words 
+    2. All cells within grid bounds
+    3. No overlapping cells
+    4. Word length distribution: exactly 2 four-letter, 2 five-letter, 2 six-letter words
+    """
     # Bounds and overlap checks
     seen: set[Coord] = set()
     counts: Dict[int, int] = {4: 0, 5: 0, 6: 0}
@@ -220,4 +230,48 @@ def sort_word_file(filepath: str) -> List[str]:
     words = [line.strip() for line in lines if line.strip() and not line.strip().startswith("#")]
     # Sort by length, then alphabetically
     sorted_words = sorted(words, key=lambda w: (len(w), w))
-    return sorted_words
+    return sorted_words
+
+def filter_word_file(filter_filepath: str, target_filepath: str) -> tuple[int, List[str]]:
+    """
+    Removes words found in filter_filepath from target_filepath.
+    Overwrites target_filepath with the filtered content.
+    Returns (number of words removed, list of removed words).
+    """
+    # Read filter words
+    try:
+        with open(filter_filepath, "r", encoding="utf-8") as f:
+            filter_words = {
+                line.strip().upper() 
+                for line in f 
+                if line.strip() and not line.strip().startswith("#")
+            }
+    except FileNotFoundError:
+        return 0, []
+
+    # Read target file lines
+    with open(target_filepath, "r", encoding="utf-8") as f:
+        lines = f.readlines()
+
+    new_lines = []
+    removed_words = []
+
+    for line in lines:
+        stripped = line.strip()
+        # Preserve comments and empty lines
+        if not stripped or stripped.startswith("#"):
+            new_lines.append(line)
+            continue
+        
+        # Check if word is in filter list
+        if stripped.upper() in filter_words:
+            removed_words.append(stripped)
+        else:
+            new_lines.append(line)
+
+    # Write back if changes were made
+    if removed_words:
+        with open(target_filepath, "w", encoding="utf-8") as f:
+            f.writelines(new_lines)
+
+    return len(removed_words), removed_words

battlewords/modules/__init__.py

@@ -20,17 +20,28 @@ from .storage import (
 )
 
 from .constants import (
+    APP_SETTINGS,
+    AI_MODELS,
     HF_API_TOKEN,
+    CRYPTO_PK,
     HF_REPO_ID,
-    SHORTENER_JSON_FILE,
     SPACE_NAME,
+    SHORTENER_JSON_FILE,
+    USE_HF_WORDS,
+    HF_WORD_LIST_REPO_ID,
+    MAX_DISPLAY_ENTRIES,
     TMPDIR,
     upload_file_types,
     model_extensions,
+    model_extensions_list,
     image_extensions,
+    image_extensions_list,
     audio_extensions,
+    audio_extensions_list,
     video_extensions,
-    doc_extensions
+    video_extensions_list,
+    doc_extensions,
+    doc_extensions_list
 )
 
 from .file_utils import (
@@ -59,17 +70,28 @@ __all__ = [
     '_list_repo_files_in_folder',
 
     # constants.py
+    'APP_SETTINGS',
+    'AI_MODELS',
     'HF_API_TOKEN',
+    'CRYPTO_PK',
     'HF_REPO_ID',
-    'SHORTENER_JSON_FILE',
     'SPACE_NAME',
+    'SHORTENER_JSON_FILE',
+    'USE_HF_WORDS',
+    'HF_WORD_LIST_REPO_ID',
+    'MAX_DISPLAY_ENTRIES',
     'TMPDIR',
     'upload_file_types',
     'model_extensions',
+    'model_extensions_list',
     'image_extensions',
+    'image_extensions_list',
     'audio_extensions',
+    'audio_extensions_list',
     'video_extensions',
+    'video_extensions_list',
     'doc_extensions',
+    'doc_extensions_list',
 
     # file_utils.py
     'get_file_parts',

battlewords/modules/constants.py

@@ -4,9 +4,11 @@ Storage-related constants for BattleWords.
 Trimmed version of OpenBadge constants - only includes what's needed for storage.py
 """
 import os
+import json
 import tempfile
 import logging
 from pathlib import Path
+from typing import Dict, Any
 from dotenv import load_dotenv
 
 # Load environment variables from .env file
@@ -21,8 +23,86 @@ CRYPTO_PK = os.getenv("CRYPTO_PK", None)
 HF_REPO_ID = os.getenv("HF_REPO_ID", "Surn/Storage")
 SPACE_NAME = os.getenv('SPACE_NAME', 'Surn/BattleWords')
 SHORTENER_JSON_FILE = "shortener.json"
+USE_HF_WORDS = os.getenv("USE_HF_WORDS", "false").lower() == "true"
+HF_WORD_LIST_REPO_ID = os.getenv("HF_WORD_LIST_REPO_ID", "ysharma/Chat_with_Meta_llama3_1_8b")
+MAX_DISPLAY_ENTRIES = int(os.getenv("MAX_DISPLAY_ENTRIES", 25))
 
+# List of smaller, faster fallback models if the primary one fails
+AI_MODELS = [
+    "microsoft/Phi-3-mini-4k-instruct",    
+    "meta-llama/Llama-3.1-8B-Instruct",
+    "google/gemma-2b-it",
+    "distilbert/distilgpt2",
+    "mistralai/Mistral-7B-Instruct-v0.3",
+    "NousResearch/Hermes-2-Pro-Llama-3-8B"    
+]
+
+# ---------------------------------------------------------------------------
+# Application Settings
+# ---------------------------------------------------------------------------
+
+def load_settings() -> Dict[str, Any]:
+    """
+    Load settings from settings.json file.
+    
+    Looks for settings.json in the project root directory.
+    Returns merged defaults with any overrides from the file.
+    Environment variables can override specific settings (e.g., GAME_TITLE).
+    
+    Returns:
+        Dict containing all application settings
+    """
+    # Path to settings.json in project root
+    settings_path = Path(__file__).parent.parent.parent / "settings.json"
+    
+    default_settings = {
+        # Game identity
+        "game_title": os.getenv("GAME_TITLE", "Battlewords"),
+        
+        # Display settings
+        "show_incorrect_guesses": True,
+        "enable_free_letters": False,
+        "show_challenge_links": True,
+        
+        # Audio settings
+        "sound_effects_enabled": True,
+        "sound_effects_volume": 30,
+        "music_enabled": False,
+        "music_volume": 10,
+        
+        # Game defaults
+        "default_wordlist": "classic.txt",
+        "default_game_mode": "classic",
+        
+        # Grid configuration (Battlewords: 12x12)
+        "grid_rows": 12,
+        "grid_cols": 12,
+        "words_per_puzzle": 6,
+        "free_letters_count": 2,
+        "max_incorrect_guesses": 10,
+        "max_display_entries": MAX_DISPLAY_ENTRIES,
+    }
+
+    try:
+        if settings_path.exists():
+            with open(settings_path, "r", encoding="utf-8") as f:
+                loaded = json.load(f)
+                # Merge with defaults (loaded settings override defaults)
+                return {**default_settings, **loaded}
+    except Exception:
+        pass
+
+    return default_settings
+
+
+# Load settings at module level for easy import
+APP_SETTINGS = load_settings()
+
+
+# ---------------------------------------------------------------------------
 # Temporary Directory Configuration
+# ---------------------------------------------------------------------------
+
 try:
     if os.environ.get('TMPDIR'):
         TMPDIR = os.environ['TMPDIR']

battlewords/settings_page.py

@@ -1,11 +1,17 @@
 from __future__ import annotations
 
 import os
+import time
 from typing import Any, Callable, Dict
 
 import streamlit as st
 
 from .local_storage import load_latest_settings, save_active_settings
+from battlewords.modules.version_info import versions_html  # version info footer
+from .generator import sort_word_file, filter_word_file
+from .audio import get_audio_tracks, _inject_audio_control_sync, get_sound_effect_files
+from .generator import sort_word_file
+from .word_loader import get_wordlist_files
 
 
 _PERSISTED_SETTING_KEYS: tuple[str, ...] = (
@@ -40,6 +46,70 @@ def _load_settings_into_session(settings: Dict[str, Any]) -> bool:
     return changed
 
 
+def _sort_wordlist(filename: str, new_game_callback: Callable[[], None]) -> None:
+
+    words_dir = os.path.join(os.path.dirname(__file__), "words")
+    filepath = os.path.join(words_dir, filename)
+    sorted_words = sort_word_file(filepath)
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        f.write("# Optional: place a large A-Z word list here (one word per line).\n")
+        f.write("# The app falls back to built-in pools if fewer than 500 words per length are found.\n")
+        for word in sorted_words:
+            f.write(f"{word}\n")
+
+    st.success(f"{filename} sorted by length and alphabetically. Starting new game in 5 seconds...")
+    time.sleep(5)
+    new_game_callback()
+
+
+def _filter_wordlist(filename: str) -> None:
+    words_dir = os.path.join(os.path.dirname(__file__), "words")
+    filepath = os.path.join(words_dir, filename)
+
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+    except Exception as exc:
+        st.error(f"Failed to read wordlist: {exc}")
+        return
+
+    header_lines = [ln for ln in lines if ln.strip().startswith("#")]
+    word_lines = [ln.strip() for ln in lines if ln.strip() and not ln.strip().startswith("#")]
+
+    # Keep only A-Z words, uppercase, lengths 4-6; dedupe while preserving order
+    kept: list[str] = []
+    seen: set[str] = set()
+    removed_count = 0
+    for raw in word_lines:
+        w = raw.strip().upper()
+        if not w.isalpha() or not w.isascii():
+            removed_count += 1
+            continue
+        if len(w) not in (4, 5, 6):
+            removed_count += 1
+            continue
+        if w in seen:
+            removed_count += 1
+            continue
+        seen.add(w)
+        kept.append(w)
+
+    with open(filepath, "w", encoding="utf-8") as f:
+        if header_lines:
+            for ln in header_lines:
+                f.write(ln if ln.endswith("\n") else ln + "\n")
+        else:
+            f.write("# Optional: place a large A-Z word list here (one word per line).\n")
+            f.write("# The app falls back to built-in pools if fewer than 500 words per length are found.\n")
+        for w in kept:
+            f.write(f"{w}\n")
+
+    st.success(
+        f"Filtered wordlist '{filename}': removed {removed_count} invalid/duplicate/out-of-range entries."
+    )
+
+
 def render_settings_page(new_game_callback: Callable[[], None]) -> None:
     """Render the Settings page.
 
@@ -77,6 +147,32 @@ def render_settings_page(new_game_callback: Callable[[], None]) -> None:
         key="game_mode",
     )
 
+    st.subheader("Wordlist Controls")
+
+    files = get_wordlist_files()
+    if files and "selected_wordlist" not in st.session_state:
+        st.session_state.selected_wordlist = "classic.txt" if "classic.txt" in files else files[0]
+
+    if files:
+        st.selectbox(
+            "Select wordlist",
+            options=files,
+            index=files.index(st.session_state.selected_wordlist)
+            if st.session_state.selected_wordlist in files
+            else 0,
+            key="selected_wordlist",
+        )
+
+        col_sort, col_filter = st.columns(2)
+        with col_sort:
+            if st.button("Sort Wordlist", key="sort_wordlist_btn", width=125):
+                _sort_wordlist(st.session_state.selected_wordlist, new_game_callback)
+        with col_filter:
+            if st.button("Filter Wordlist", key="filter_wordlist_btn", width=125):
+                _filter_wordlist(st.session_state.selected_wordlist)
+    else:
+        st.info("No word lists found in words/ directory.")
+
     if "show_grid_ticks" not in st.session_state:
         st.session_state.show_grid_ticks = False
     st.checkbox("Show grid ticks", key="show_grid_ticks")
@@ -101,7 +197,21 @@ def render_settings_page(new_game_callback: Callable[[], None]) -> None:
         st.session_state.show_challenge_share_links = False
     st.checkbox("Show challenge share links", key="show_challenge_share_links")
 
-    st.subheader("Audio")
+    # Audio settings
+    st.header("Audio")
+
+    # --- List sound effects in effects folder ---
+    effects = get_sound_effect_files()
+    if effects:
+        effect_list = ", ".join(sorted(effects.keys()))
+        st.caption(f"Sound effects found in wrdler/assets/audio/effects: {effect_list}")
+    else:
+        st.caption("No sound effects found in wrdler/assets/audio/effects.")
+
+    if "music_enabled" not in st.session_state:
+        st.session_state.music_enabled = False
+    if "music_volume" not in st.session_state:
+        st.session_state.music_volume = 15
 
     if "enable_sound_effects" not in st.session_state:
         st.session_state.enable_sound_effects = True
@@ -118,31 +228,53 @@ def render_settings_page(new_game_callback: Callable[[], None]) -> None:
         key="effects_volume",
     )
 
-    if "music_enabled" not in st.session_state:
-        st.session_state.music_enabled = False
-    st.checkbox("Enable music", key="music_enabled")
+    tracks = get_audio_tracks()
+    st.caption(f"{len(tracks)} audio file{'s' if len(tracks) != 1 else ''} found in wrdler/assets/audio/music")
+
+    enabled = st.checkbox("Enable music", value=st.session_state.music_enabled, key="music_enabled")
 
-    if "music_volume" not in st.session_state:
-        st.session_state.music_volume = 15
     st.slider(
-        "Music volume",
+        "Volume",
         0,
         100,
         value=int(st.session_state.music_volume),
         step=1,
         key="music_volume",
-        disabled=not st.session_state.music_enabled,
+        disabled=not (enabled and bool(tracks)),
     )
 
+    selected_path = None
+    if tracks:
+        options = [p for _, p in tracks]
+        # Default to first track if none chosen yet
+        if "music_track_path" not in st.session_state or st.session_state.music_track_path not in options:
+            st.session_state.music_track_path = options[0]
+
+        def _fmt(p: str) -> str:
+            # Find friendly label for path
+            for name, path in tracks:
+                if path == p:
+                    return name
+            return os.path.splitext(os.path.basename(p))[0]
+
+        selected_path = st.selectbox(
+            "Track",
+            options=options,
+            index=options.index(st.session_state.music_track_path),
+            format_func=_fmt,
+            key="music_track_path",
+            disabled=not enabled,
+        )
+    else:
+        st.caption("Place .mp3 files in wrdler/assets/audio/music to enable music.")
+
     st.markdown("---")
 
     col_apply, col_reset = st.columns(2)
 
     with col_apply:
-        if st.button("Save & Apply", key="settings_save_apply", width="stretch"):
-            snapshot = {
-                key: st.session_state.get(key) for key in _PERSISTED_SETTING_KEYS
-            }
+        if st.button("Save & Apply", key="settings_save_apply_btn", width="stretch"):
+            snapshot = {key: st.session_state.get(key) for key in _PERSISTED_SETTING_KEYS}
             save_active_settings(snapshot)
             st.session_state["_settings_saved_notice"] = "Settings saved."
             new_game_callback()
@@ -153,7 +285,7 @@ def render_settings_page(new_game_callback: Callable[[], None]) -> None:
             st.rerun()
 
     with col_reset:
-        if st.button("Discard changes", key="settings_discard", width="stretch"):
+        if st.button("Discard changes", key="settings_discard_btn", width="stretch"):
             latest = load_latest_settings()
             if latest:
                 _load_settings_into_session(latest)
@@ -165,3 +297,5 @@ def render_settings_page(new_game_callback: Callable[[], None]) -> None:
 
     settings_dir = os.path.join(os.path.dirname(__file__), "settings")
     st.caption(f"Settings are stored locally under: {settings_dir}")
+
+    st.markdown(versions_html(), unsafe_allow_html=True)

battlewords/ui.py

@@ -14,11 +14,10 @@ import numpy as np
 import time
 from datetime import datetime
 
-from .generator import generate_puzzle, sort_word_file
+from .generator import generate_puzzle
 from .logic import build_letter_map, reveal_cell, guess_word, is_game_over, compute_tier, auto_mark_completed_words, hidden_word_display
 from .models import Coord, GameState, Puzzle
 from .word_loader import get_wordlist_files, load_word_list, compute_word_difficulties
-from battlewords.modules.version_info import versions_html  # version info footer
 from .audio import (
     _get_music_dir,
     get_audio_tracks,
@@ -29,143 +28,12 @@ from .audio import (
 )
 from .game_storage import load_game_from_sid, save_game_to_hf, get_shareable_url, add_user_result_to_game
 from .settings_page import render_settings_page
-from .ui_helpers import render_footer
-
-# PWA (Progressive Web App) Support
-# Enables installing BattleWords as a native-feeling mobile app
-# Note: PWA meta tags are injected into <head> via Docker build (inject-pwa-head.sh)
-# This ensures proper PWA detection by browsers
-pwa_service_worker = """
-<script>
-// Register service worker for offline functionality
-// Note: Using inline Blob URL to bypass Streamlit's text/plain content-type for .js files
-if ('serviceWorker' in navigator) {
-  window.addEventListener('load', () => {
-    // Service worker code as string (inline to avoid MIME type issues)
-    const swCode = `
-const CACHE_NAME = 'battlewords-v0.2.29';
-const RUNTIME_CACHE = 'battlewords-runtime';
-
-const PRECACHE_URLS = [
-  '/',
-  '/app/static/manifest.json',
-  '/app/static/icon-192.png',
-  '/app/static/icon-512.png'
-];
-
-self.addEventListener('install', event => {
-  console.log('[ServiceWorker] Installing...');
-  event.waitUntil(
-    caches.open(CACHE_NAME)
-      .then(cache => {
-        console.log('[ServiceWorker] Precaching app shell');
-        return cache.addAll(PRECACHE_URLS);
-      })
-      .then(() => self.skipWaiting())
-  );
-});
-
-self.addEventListener('activate', event => {
-  console.log('[ServiceWorker] Activating...');
-  event.waitUntil(
-    caches.keys().then(cacheNames => {
-      return Promise.all(
-        cacheNames.map(cacheName => {
-          if (cacheName !== CACHE_NAME && cacheName !== RUNTIME_CACHE) {
-            console.log('[ServiceWorker] Deleting old cache:', cacheName);
-            return caches.delete(cacheName);
-          }
-        })
-      );
-    }).then(() => self.clients.claim())
-  );
-});
-
-self.addEventListener('fetch', event => {
-  if (event.request.method !== 'GET') return;
-  if (!event.request.url.startsWith('http')) return;
-
-  event.respondWith(
-    caches.open(RUNTIME_CACHE).then(cache => {
-      return fetch(event.request)
-        .then(response => {
-          if (response.status === 200) {
-            cache.put(event.request, response.clone());
-          }
-          return response;
-        })
-        .catch(() => {
-          return caches.match(event.request).then(cachedResponse => {
-            if (cachedResponse) {
-              console.log('[ServiceWorker] Serving from cache:', event.request.url);
-              return cachedResponse;
-            }
-            return new Response('Offline - Please check your connection', {
-              status: 503,
-              statusText: 'Service Unavailable',
-              headers: new Headers({'Content-Type': 'text/plain'})
-            });
-          });
-        });
-    })
-  );
-});
-
-self.addEventListener('message', event => {
-  if (event.data.action === 'skipWaiting') {
-    self.skipWaiting();
-  }
-});
-`;
-
-    // Create Blob URL for service worker
-    const blob = new Blob([swCode], { type: 'application/javascript' });
-    const swUrl = URL.createObjectURL(blob);
-
-    navigator.serviceWorker.register(swUrl)
-      .then(registration => {
-        console.log('[PWA] Service Worker registered successfully:', registration.scope);
-
-        registration.addEventListener('updatefound', () => {
-          const newWorker = registration.installing;
-          newWorker.addEventListener('statechange', () => {
-            if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
-              console.log('[PWA] New version available! Refresh to update.');
-            }
-          });
-        });
-      })
-      .catch(error => {
-        console.log('[PWA] Service Worker registration failed:', error);
-      });
-  });
-}
-
-// Prompt user to install PWA (for browsers that support it)
-let deferredPrompt;
-window.addEventListener('beforeinstallprompt', (e) => {
-  console.log('[PWA] Install prompt available');
-  e.preventDefault();
-  deferredPrompt = e;
-  // Could show custom install button here if desired
-});
-
-// Track when user installs the app
-window.addEventListener('appinstalled', () => {
-  console.log('[PWA] BattleWords installed successfully!');
-  deferredPrompt = null;
-});
-</script>
-"""
+from .ui_helpers import render_footer, inject_styles, fig_to_pil_rgba, ocean_background_css, inject_ocean_layers, pwa_service_worker
+
 
 CoordLike = Tuple[int, int]
 
-def fig_to_pil_rgba(fig):
-    canvas = FigureCanvas(fig)
-    canvas.draw()
-    w, h = fig.canvas.get_width_height()
-    img = np.frombuffer(canvas.buffer_rgba(), dtype=np.uint8).reshape(h, w, 4)
-    return Image.fromarray(img, mode="RGBA")
+
 
 def _coord_to_xy(c) -> CoordLike:
     # Supports dataclass Coord(x, y) or a 2-tuple/list.
@@ -191,308 +59,8 @@ def _build_letter_map(puzzle) -> dict[CoordLike, str]:
                 letters[xy] = text[i]
     return letters
 
-ocean_background_css = """
-<style>
-:root {
-  --water-deep: #0b2a4a;
-  --water-mid:  #0f3968;
-  --water-lite: #165ba8;
-  --water-sky:  #1d64c8;
-  --foam:       rgba(255,255,255,0.18);
-}
-
-.stAppHeader{
-    opacity:0.6;
-}
-
-.stApp {
-  margin: 0;
-  min-height: 100vh;
-  overflow: hidden;  /* prevent scrollbars from animated layers */
-  background-attachment: scroll;
-  position: relative;
-
-  /* Static base gradient */
-  background-image:
-    linear-gradient(180deg, var(--water-sky) 0%, var(--water-lite) 35%, var(--water-mid) 70%, var(--water-deep) 100%);
-  background-size: 100% 100%;
-  background-position: 50% 50%;
-
-  animation: none !important;
-  will-change: background-position;
-}
-
-/* Animated overlay waves (under bg layers) */
-.stApp::before {
-  content: "";
-  position: absolute;
-  inset: -10% -10%;
-  z-index: 0;
-  pointer-events: none;
-  background:
-    repeating-linear-gradient(0deg, rgba(255,255,255,0.10) 0 2px, transparent 2px 22px),
-    repeating-linear-gradient(90deg, rgba(255,255,255,0.06) 0 1px, transparent 1px 18px);
-  mix-blend-mode: screen;
-  opacity: 0.10;
-  /*animation: waveOverlayScroll 16s linear infinite;*/
-}
-.stIFrame {
-    margin-bottom:25px;
-}
-
-@keyframes waveOverlayScroll {
-  0%   { background-position:   0px   0px,   0px   0px; }
-  100% { background-position: -800px   0px,   0px -600px; }
-}
-
-/* Keep Streamlit content above background/overlay */
-.stApp > div { position: relative; z-index: 5; }
-
-/* Slower, more subtle animations */
-@keyframes oceanHighlight {
-  0%   { background-position: 50% 0%; }
-  50%  { background-position: 60% 8%; }
-  100% { background-position: 50% 0%; }
-}
-
-@keyframes oceanLong {
-  0%   { background-position: 0% 50%; }
-  100% { background-position: -100% 50%; }
-}
-
-@keyframes oceanMid {
-  0%   { background-position: 100% 50%; }
-  100% { background-position: 200% 50%; }
-}
-
-@keyframes oceanFine {
-  0%   { background-position: 0% 50%; }
-  100% { background-position: 100% 50%; }
-}
-
-/* Reduced motion */
-@media (prefers-reduced-motion: reduce) {
-  .stApp, .stApp::before { animation: none; }
-}
-</style>
-"""
-
-def inject_ocean_layers() -> None:
-    st.markdown(
-        """
-        <style>
-          .bw-bg-container {
-            position: fixed;     /* fixed to viewport, not stApp */
-            inset: 0;
-            z-index: 1;          /* below content (z=5) but above ::before (z=0) */
-            pointer-events: none;
-            overflow: hidden;    /* clip children */
-          }
-          .bw-bg-layer {
-            position: absolute;
-            inset: 0;
-            width: 100vw;
-            height: 100vh;
-            pointer-events: none;
-          }
-          /* Explicit stacking order with slower animations */
-          .bw-bg-highlight { 
-            z-index: 11; 
-            background: radial-gradient(150% 100% at 50% -20%, rgba(255,255,255,0.10) 0%, transparent 60%); 
-            background-size: 150% 150%;  /* reduced from 300% */
-            /* animation: oceanHighlight 12s ease-in-out infinite; */ /* doubled from 6s */
-          }
-          .bw-bg-long { 
-            z-index: 12; 
-            background: repeating-linear-gradient(-6deg, rgba(255,255,255,0.08) 0px, rgba(255,255,255,0.08) 18px, rgba(0,0,0,0.04) 18px, rgba(0,0,0,0.04) 48px); 
-            background-size: 150% 150%;  /* reduced from 320% */
-            /* animation: oceanLong 36s linear infinite; */  /* doubled from 18s */
-            opacity: 0.2; 
-          }
-          .bw-bg-mid { 
-            z-index: 13; 
-            background: repeating-linear-gradient(-12deg, rgba(255,255,255,0.10) 0px, rgba(255,255,255,0.10) 10px, rgba(0,0,0,0.05) 10px, rgba(0,0,0,0.05) 26px); 
-            background-size: 150% 150%;  /* reduced from 260% */
-            /* animation: oceanMid 24s linear infinite; */  /* doubled from 12s */
-            opacity: 0.2; 
-          }
-          .bw-bg-fine { 
-            z-index: 14; 
-            background: repeating-linear-gradient(-18deg, var(--foam) 0px, var(--foam) 4px, transparent 4px, transparent 12px); 
-            background-size: 120% 120%;  /* reduced from 200% */
-            animation: oceanFine 14s linear infinite;  /* doubled from 7s */
-            opacity: 0.15; 
-          }
-        </style>
-        <div class="bw-bg-container">
-          <div class="bw-bg-layer bw-bg-highlight"></div>
-          <div class="bw-bg-layer bw-bg-long"></div>
-          <div class="bw-bg-layer bw-bg-mid"></div>
-          <div class="bw-bg-layer bw-bg-fine"></div>
-        </div>
-        """,
-        unsafe_allow_html=True,
-    )
-
-def inject_styles() -> None:
-    st.markdown(
-        """
-        <style>
-            /* Center main content and limit width */
-            # .stApp, body {
-            #     background: rgba(29, 100, 200, 0.5);
-            # }
-           .stMainBlockContainer {
-            max-width: 1100px;
-           }
-           .stHeading {
-                margin-bottom: -1.5rem !important;
-                margin-top: -1.5rem !important;
-                # font-size: 1.75rem !important; /* Title */
-                line-height: 1.1 !important;
-           }
-           #reveal-letters-in-cells-then-guess-the-words {
-            font-size: 16px !important; /* Subheader */
-            margin-top: .1rem !important;
-           }
-          /* Base grid cell visuals */
-          .bw-row { display: flex; gap: 0.1rem; flex-wrap: nowrap; min-height: 48px;}
-          .bw-cell {
-            width: 100%;
-            gap: 0.1rem;
-            aspect-ratio: 1 / 1;
-            line-height: 1.6;
-            display: flex;
-            align-items: center;
-            justify-content: center;
-            border: 1px solid #1d64c8;
-            border-radius: 0;
-            font-weight: 700;
-            user-select: none;
-            padding: 0.5rem 0.75rem;
-            font-size: 1.4rem;
-            min-height: 2.5rem;
-            min-width: 1.25em;
-            transition: background 0.2s ease, color 0.2s ease, border-color 0.2s ease;
-            background: #1d64c8;   /* Base cell color */
-            color: #FFFFFF;         /* Base text color for contrast */
-          }
-          /* Found letter cells */
-          .bw-cell.letter { background: #d7faff; color: #050057; }
-          /* Optional empty state if ever used */
-          .bw-cell.empty  { background: #3a3a3a; color: #ffffff;}
-          /* Completed word cells */
-          .bw-cell.bw-cell-complete { background: #050057 !important; color: #d7faff !important; }
-
-          /* Final score style */
-          .bw-final-score { color: #1ca41c !important; font-weight: 800; }
-          .stExpander {z-index: 10;width: 50%;}
-          div[data-testid="stToastContainer"], div[data-testid="stToast"] {
-            margin: 0 auto;
-          }
-
-          /* Make grid buttons square and fill their column */
-          div[data-testid="stButton"]{
-            margin: 0 auto;
-            text-align: center;
-          }
-          div[data-testid="stButton"] button { max-width: 100%; aspect-ratio: 1 / 1; border-radius: 0; background: #1d64c8; color: #ffffff; font-weight: 700; padding: 0.5rem 0.75rem; min-height: 2.5rem; min-width: 2.5rem;}
-          .st-key-new_game_btn, .st-key-sort_wordlist_btn { margin: 0 auto; aspect-ratio: unset; }
-          .st-key-new_game_btn > div[data-testid="stButton"] button, .st-key-sort_wordlist_btn > div[data-testid="stButton"] button { aspect-ratio: unset; text-align:center; height: auto;}
-
-          div[data-testid="column"], .st-emotion-cache-zh2fnc { width: auto !important; flex: 1 1 auto !important; min-width: 100% !important; max-width: 100% !important; }
-          .st-emotion-cache-1permvm, .st-emotion-cache-1n6tfoc { gap:0.15rem !important; min-height: 2.5rem; min-width: 2.5rem;}          
-
-          .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, #a1a1a1, #ffffff, #a1a1a1, #666666); gap: 0.1rem !important; color: white; border-radius:15px; padding: 10px 10px 10px 5px; }
-          .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; }
-
-          /* grid adjustments */
-          @media (min-width: 560px){
-           div[data-testid="stButton"] button { max-width: 100%; aspect-ratio: 1 / 1; min-height: calc(100% + 20px) !important;}           
-           .st-key-new_game_btn > div[data-testid="stButton"] button, .st-key-sort_wordlist_btn > div[data-testid="stButton"] button { min-height: calc(100% + 20px) !important;}
-           .st-emotion-cache-ckafi0 { gap:0.1rem !important; min-height: calc(100% + 20px) !important; aspect-ratio: 1 / 1; width: auto !important;  flex: 1 1 auto !important;  min-width: 100% !important;  max-width: 100% !important;}
-           /*.st-emotion-cache-1n6tfoc { aspect-ratio: 1 / 1; min-height: calc(100% + 20px) !important;}*/
-           .st-emotion-cache-1n6tfoc::before { min-height: calc(100% + 20px) !important; }
-
-          }
-          div[data-testid="stElementToolbarButtonContainer"], button[data-testid="stBaseButton-elementToolbar"], button[data-testid="stBaseButton-elementToolbar"]:hover {
-               display: none;
-          }
-
-          /* Mobile styles */
-          @media (max-width: 640px) {
-            .bw-cell, div[data-testid="stButton"] button, .st-emotion-cache-1permvm {min-width: 1.5rem; min-height:40px;}
-            #bw-main-anchor + div[data-testid="stHorizontalBlock"] { flex-direction: column-reverse !important; width: 100% !important; max-width: 100vw !important; }
-            #bw-main-anchor + div[data-testid="stHorizontalBlock"] > div[data-testid="column"] { width: 100% !important; min-width: 100% !important; max-width: 100% !important; flex: 1 1 100% !important; }
-            .bw-grid-row-anchor + div[data-testid="stHorizontalBlock"] { flex-wrap: nowrap !important; overflow-x: auto !important; margin: 2px 0 !important; }
-            .st-emotion-cache-17i4tbh { min-width: calc(8.33333% - 1rem); }
-          }
-
-          .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; }
-          .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;}
-          .bw-score-panel-container table tbody tr h3 {display: flex;flex-direction: row;justify-content: space-evenly;flex-wrap: wrap;}
-          .shiny-border:hover::before { left: 100%; }
-
-          .bw-radio-group { display:flex; align-items:flex-start; gap: 10px; flex-flow: row; }
-          .bw-radio-item { display:flex; flex-direction:column; align-items:center; gap:6px; text-align:center;}
-          .bw-radio-circle { width: 45px; height: 45px; border-radius: 50%; border: 4px solid; background: rgba(255,255,255,0.06); display: grid; place-items: center; color:#fff; font-weight:700; }
-          .bw-radio-circle .dot { width: 14px; height: 14px; border-radius: 50%; background:#777; box-shadow: inset 0 0 0 2px rgba(255,255,255,0.25); }
-          .bw-radio-circle.active.hit { background: linear-gradient(135deg, rgba(0,255,127,0.18), rgba(0,128,64,0.38)); }
-          .bw-radio-circle.active.hit .dot { background:#20d46c; box-shadow: 0 0 10px rgba(32,212,108,0.85); }
-          .bw-radio-circle.active.miss { background: linear-gradient(135deg, rgba(255,0,0,0.18), rgba(128,0,0,0.38)); }
-          .bw-radio-circle.active.miss .dot { background:#ff4b4b; box-shadow: 0 0 10px rgba(255,75,75,0.85); }
-          .bw-radio-caption { font-size: 0.8rem; color:#fff; opacity:0.85; letter-spacing:0.5px; }
-          @media (max-width:1000px) and (min-width:641px) {
-            .bw-radio-group { flex-wrap:wrap; gap: 5px; margin-bottom: 5px;}
-            .bw-radio-item {margin: 0 auto;}
-          }
-          @media (max-width:640px) {
-            .bw-radio-item { margin:unset;}
-          }
-
-          /* Make the sidebar scrollable */
-          section[data-testid="stSidebar"] {
-              max-height: 100vh;
-              overflow-y: auto;
-              overflow-x: hidden;
-              scrollbar-width: thin;
-              scrollbar-color: transparent transparent;
-              opacity:0.75;
-          }
 
-         .st-emotion-cache-wp60of {
-             width: 720px;
-             position: absolute;     
-             max-width:100%;
-          }
-         .stImage {max-width:240px;}
-         [id^="text_input"] {
-          background-color:#fff;
-          color:#000;
-          caret-color:#333;}
-        
-         @media (min-width:720px) {         
-          .st-emotion-cache-wp60of {
-            left: calc(calc(100% - 720px) / 2);
-          }
-         }
 
-          /* Helper to absolutely/fixed position Streamlit component wrapper when showing modal */
-          .bw-component-abs { position: fixed !important; inset: 0 !important; z-index: 99999 !important; width: 100vw !important; height: 100vh !important; margin: 0 !important; padding: 0 !important; }
-          /* Generic hide utility */
-          .hide { display: none !important; pointer-events: none !important; }
-        </style>
-        """,
-        unsafe_allow_html=True,
-    )
 
 def _init_session() -> None:
     if "initialized" in st.session_state and st.session_state.initialized:
@@ -564,6 +132,13 @@ def _init_session() -> None:
     # NEW: Initialize Show Challenge Share Links (default OFF)
     if "show_challenge_share_links" not in st.session_state:
         st.session_state.show_challenge_share_links = 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:
+        st.session_state.enable_sound_effects = False
 
 def _new_game() -> None:
  selected = st.session_state.get("selected_wordlist")
@@ -1009,7 +584,7 @@ def _render_grid(state: GameState, letter_map, show_grid_ticks: bool = True):
             .st-emotion-cache-ig7yu6 {
                 min-width: calc(30% - 1.5rem);
             }
-            .st-emotion-cache-15oaysa, .st-emotion-cache-8ocv8  {
+            .st-emotion-cache-15oaysa, .st-emotion-cache-8ocv8, .st-emotion-cache-1yoilpv  {
                 min-width: calc(8.33333% - 1rem);
             }
         }
@@ -1100,25 +675,6 @@ def _render_grid(state: GameState, letter_map, show_grid_ticks: bool = True):
 
         st.rerun()
 
-def _sort_wordlist(filename):
-    import os
-    import time  # Add this import
-
-    WORDS_DIR = os.path.join(os.path.dirname(__file__), "words")
-    filepath = os.path.join(WORDS_DIR, filename)
-    sorted_words = sort_word_file(filepath)
-    # Optionally, write sorted words back to file
-    with open(filepath, "w", encoding="utf-8") as f:
-        # Re-add header if needed
-        f.write("# Optional: place a large A–Z word list here (one word per line).\n")
-        f.write("# The app falls back to built-in pools if fewer than 500 words per length are found.\n")
-        for word in sorted_words:
-            f.write(f"{word}\n")
-    # Show a message in Streamlit
-    st.success(f"{filename} sorted by length and alphabetically. Starting new game in 5 seconds...")
-    time.sleep(5)  # 5 second delay before starting new game
-    _new_game()
-
 def _render_hit_miss(state: GameState):
     # Determine last reveal outcome from last_action string
     action = (state.last_action or "").strip()
@@ -1162,6 +718,18 @@ def _render_guess_form(state: GameState):
     if "incorrect_guesses" not in st.session_state:
         st.session_state.incorrect_guesses = []
 
+    # Enable guessing after correct guess or letter reveal
+    action = (state.last_action or "").strip()
+    if action.startswith("Correct!") or action.startswith("Revealed '"):
+        st.session_state.can_guess = True
+    else:
+        if state.game_mode in ("easy", "too easy"):
+            if action.startswith("Revealed '") or action.startswith("Revealed empty"):
+                st.session_state.can_guess = True
+        else:
+            if action.startswith("Revealed '"):
+                st.session_state.can_guess = True
+
     # Prepare tooltip text for native browser tooltip (stack vertically)
     recent_incorrect = st.session_state.incorrect_guesses[-10:]
     if st.session_state.get("show_incorrect_guesses", True) and recent_incorrect:
@@ -1222,6 +790,10 @@ def _render_guess_form(state: GameState):
             font-size: 0.8rem;
             cursor: help;
         }
+        .st-key-guess_input .stTooltipIcon .stTooltipHoverTarget:hover::after {
+            font-size: 0.8rem;
+            cursor: help;
+        }
         .st-key-guess_input .stTooltipIcon .stTooltipHoverTarget:hover::after {
             color: #ff9999;
         }
@@ -1229,17 +801,30 @@ def _render_guess_form(state: GameState):
         .stForm { padding-bottom: 30px; }
 
         @media (max-width: 640px) {
-            .st-emotion-cache-1xwdq91, .st-emotion-cache-1r70o5b {
-                max-width: max-content; min-width:33%;
-            }
+          .st-emotion-cache-1xwdq91, .st-emotion-cache-1r70o5,  {
+              max-width: max-content; min-width:33%;
+          }
+          .st-emotion-cache-emqb34, .st-emotion-cache-192m4g1 {
+            min-width: calc(50% - 1.5rem);
+            width: calc(50% - 1.5rem);
+            flex:unset;
+          }
+          .st-emotion-cache-1c94k11, .st-emotion-cache-abr9nb {
+            min-width: calc(50% - 1.5rem);
+            width: calc(50% - 1.5rem);
+            flex:unset;
+          }
+          .st-emotion-cache-bw9c3d, .st-emotion-cache-1w9nhvb, .st-emotion-cache-bah2wz, .st-emotion-cache-tuze3w, .st-emotion-cache-nwgyir, .st-emotion-cache-1pzr114 {
+            min-width: unset;
+          }
         }
         </style>
         """,
         unsafe_allow_html=True,
     )
     
-    with st.form("guess_form", width=300, clear_on_submit=True):
-        col1, col2 = st.columns([2, 1], vertical_alignment="bottom")
+    with st.form("guess_form", width="stretch", clear_on_submit=True):
+        col1, col2, col3 = st.columns([0.4, 0.25, 0.35], vertical_alignment="bottom")
         with col1:
             guess_text = st.text_input(
                 "Your Guess", 
@@ -1251,6 +836,8 @@ def _render_guess_form(state: GameState):
             )
         with col2:
             submitted = st.form_submit_button("OK", disabled=not state.can_guess, width=100, key="guess_submit")
+        with col3:
+            _render_correct_try_again(state)
         
         # Show compact list below input if setting is enabled
         #if st.session_state.get("show_incorrect_guesses", True) and recent_incorrect:
@@ -1260,19 +847,21 @@ def _render_guess_form(state: GameState):
         #    )
         
         if submitted:
-            correct, _ = guess_word(state, guess_text)
-            _sync_back(state)
-            # Invalidate radar GIF cache if guess changed the set of guessed words
-            if correct:
-                st.session_state.radar_gif_path = None
-                st.session_state.radar_gif_signature = None
-                play_sound_effect("correct_guess", volume=(st.session_state.get("effects_volume", 50) / 100))
-            else:
-                # Update incorrect guesses list - keep only last 10
-                st.session_state.incorrect_guesses.append(guess_text)
-                st.session_state.incorrect_guesses = st.session_state.incorrect_guesses[-10:]
-                play_sound_effect("incorrect_guess", volume=(st.session_state.get("effects_volume", 50) / 100))
-            st.rerun()
+            # Only process guesses with at least 4 characters (prevent blank/short submissions)
+            if len(guess_text.strip()) >= 4:
+                correct, _ = guess_word(state, guess_text)
+                _sync_back(state)
+                # Invalidate radar GIF cache if guess changed the set of guessed words
+                if correct:
+                    st.session_state.radar_gif_path = None
+                    st.session_state.radar_gif_signature = None
+                    play_sound_effect("correct_guess", volume=(st.session_state.get("effects_volume", 50) / 100))
+                else:
+                    # Update incorrect guesses list - keep only last 10
+                    st.session_state.incorrect_guesses.append(guess_text)
+                    st.session_state.incorrect_guesses = st.session_state.incorrect_guesses[-10:]
+                    play_sound_effect("incorrect_guess", volume=(st.session_state.get("effects_volume", 50) / 100))
+                st.rerun()
 
 
 # -------------------- Score Panel --------------------
@@ -1340,12 +929,14 @@ def _render_score_panel(state: GameState):
     <div class='bw-score-panel-container'>
       <style>
         .bold-text {{ font-weight: 700; }}
-        .blue-background {{ background:#1d64c8; opacity:0.9; color:#fff; }}
-        .shiny-border {{ position: relative; padding: 12px; background: #333; color: white; border-radius: 1.25rem; overflow: hidden; }}
+        .blue-background {{ background:#1d64c8dd; opacity:0.9; color:#fff; }}
+        .shiny-border {{ position: relative; padding: 10px; background: #333; color: white; border-radius: 1.25rem; overflow: hidden; }}
         .bw-score-panel-container {{ height: 100%; overflow: hidden; text-align:center;}}
         .bw-score-panel-container table tbody tr h3 {{display: flex;flex-direction: row;justify-content: space-evenly;flex-wrap: wrap;}}
+
         table {{ width: 100%; margin: 0 auto; border-collapse: separate; border-spacing: 0; }}
-        th, td {{ padding: 6px 8px; }}
+        th, td {{ padding: 3px 4px; }}
+
       </style>
       <table class='shiny-border' style="background: linear-gradient(-45deg, #a1a1a1, #ffffff, #a1a1a1, #666666);">
         {table_inner}
@@ -1820,7 +1411,7 @@ def run_app():
 
     if page == "settings":
         st.markdown(ocean_background_css, unsafe_allow_html=True)
-        inject_ocean_layers()
+        #inject_ocean_layers()
         inject_styles()
         render_settings_page(_on_game_option_change)
         render_footer(current_page="settings")
@@ -1828,7 +1419,7 @@ def run_app():
 
     if page == "leaderboard":
         st.markdown(ocean_background_css, unsafe_allow_html=True)
-        inject_ocean_layers()
+        #inject_ocean_layers()
         inject_styles()
         st.header("Leaderboard")
         st.caption("Leaderboard UI will be added as part of the upgrade checklist.")
@@ -1865,12 +1456,12 @@ def run_app():
 
     _init_session()
     st.markdown(ocean_background_css, unsafe_allow_html=True)
-    inject_ocean_layers()  # <-- add the animated layers
+    #inject_ocean_layers()  # <-- add the animated layers
     _render_header()    
 
     state = _to_state()
 
-    st.markdown('<div id="bw-main-anchor"></div>', unsafe_allow_html=True)
+    st.markdown('<div id="bw-main-anchor"></div>', unsafe_allow_html=True)    
     left, right = st.columns([3, 2], gap="medium")
     with right:
         _render_radar(
@@ -1882,19 +1473,20 @@ def run_app():
             stagger_radar=False,
             show_ticks=st.session_state.get("show_grid_ticks", False),
         )
-        one, two = st.columns([1, 2], gap="medium")
-        with one:
-            _render_correct_try_again(state)
-        with two:
-            _render_guess_form(state)
+        # one, two = st.columns([1, 2], gap="medium")
+        # with one:
+        #     _render_correct_try_again(state)
+        # with two:
+        _render_guess_form(state)
         _render_score_panel(state)
     with left:
+        st.button("New Game", width=125, on_click=_new_game, key="new_game_btn")
         _render_grid(
             state,
             st.session_state.letter_map,
             show_grid_ticks=st.session_state.get("show_grid_ticks", True),
         )
-        st.button("New Game", width=125, on_click=_new_game, key="new_game_btn")
+        
 
     # End condition (only show overlay if dismissed)
     state = _to_state()

battlewords/ui_helpers.py

@@ -3,8 +3,477 @@ from __future__ import annotations
 from typing import Optional
 
 import streamlit as st
+import numpy as np
+from PIL import Image
+from matplotlib.backends.backend_agg import FigureCanvasAgg as FigureCanvas
+from . import __version__ as version
+from .modules.constants import APP_SETTINGS
+import base64
+import os
 
+def fig_to_pil_rgba(fig):
+    canvas = FigureCanvas(fig)
+    canvas.draw()
+    w, h = fig.canvas.get_width_height()
+    img = np.frombuffer(canvas.buffer_rgba(), dtype=np.uint8).reshape(h, w, 4)
+    return Image.fromarray(img, mode="RGBA")
 
+def get_effective_game_title() -> str:
+    """
+    Get the effective game title, prioritizing:
+    1. Challenge-specific game_title from shared_game_settings
+    2. Session state game_title (if set)
+    3. APP_SETTINGS default
+    4. Fallback to "Wrdler"
+    Returns:
+        str: The effective game title.
+    """
+    # First check shared game settings (challenge mode)
+    shared_settings = st.session_state.get("shared_game_settings")
+    if shared_settings and shared_settings.get("game_title"):
+        return shared_settings["game_title"]
+    
+    # Then check session state
+    if st.session_state.get("game_title"):
+        return st.session_state["game_title"]
+    
+    # Fall back to APP_SETTINGS
+    return APP_SETTINGS.get("game_title", "Battlewords")
+
+# PWA (Progressive Web App) Support
+# Enables installing BattleWords as a native-feeling mobile app
+# Note: PWA meta tags are injected into <head> via Docker build (inject-pwa-head.sh)
+# This ensures proper PWA detection by browsers
+pwa_service_worker = """
+<script>
+// Register service worker for offline functionality
+// Note: Using inline Blob URL to bypass Streamlit's text/plain content-type for .js files
+if ('serviceWorker' in navigator) {
+  window.addEventListener('load', () => {
+    // Service worker code as string (inline to avoid MIME type issues)
+    const swCode = `
+const CACHE_NAME = 'battlewords-v0.2.29';
+const RUNTIME_CACHE = 'battlewords-runtime';
+
+const PRECACHE_URLS = [
+  '/',
+  '/app/static/manifest.json',
+  '/app/static/icon-192.png',
+  '/app/static/icon-512.png'
+];
+
+self.addEventListener('install', event => {
+  console.log('[ServiceWorker] Installing...');
+  event.waitUntil(
+    caches.open(CACHE_NAME)
+      .then(cache => {
+        console.log('[ServiceWorker] Precaching app shell');
+        return cache.addAll(PRECACHE_URLS);
+      })
+      .then(() => self.skipWaiting())
+  );
+});
+
+self.addEventListener('activate', event => {
+  console.log('[ServiceWorker] Activating...');
+  event.waitUntil(
+    caches.keys().then(cacheNames => {
+      return Promise.all(
+        cacheNames.map(cacheName => {
+          if (cacheName !== CACHE_NAME && cacheName !== RUNTIME_CACHE) {
+            console.log('[ServiceWorker] Deleting old cache:', cacheName);
+            return caches.delete(cacheName);
+          }
+        })
+      );
+    }).then(() => self.clients.claim())
+  );
+});
+
+self.addEventListener('fetch', event => {
+  if (event.request.method !== 'GET') return;
+  if (!event.request.url.startsWith('http')) return;
+
+  event.respondWith(
+    caches.open(RUNTIME_CACHE).then(cache => {
+      return fetch(event.request)
+        .then(response => {
+          if (response.status === 200) {
+            cache.put(event.request, response.clone());
+          }
+          return response;
+        })
+        .catch(() => {
+          return caches.match(event.request).then(cachedResponse => {
+            if (cachedResponse) {
+              console.log('[ServiceWorker] Serving from cache:', event.request.url);
+              return cachedResponse;
+            }
+            return new Response('Offline - Please check your connection', {
+              status: 503,
+              statusText: 'Service Unavailable',
+              headers: new Headers({'Content-Type': 'text/plain'})
+            });
+          });
+        });
+    })
+  );
+});
+
+self.addEventListener('message', event => {
+  if (event.data.action === 'skipWaiting') {
+    self.skipWaiting();
+  }
+});
+`;
+
+    // Create Blob URL for service worker
+    const blob = new Blob([swCode], { type: 'application/javascript' });
+    const swUrl = URL.createObjectURL(blob);
+
+    navigator.serviceWorker.register(swUrl)
+      .then(registration => {
+        console.log('[PWA] Service Worker registered successfully:', registration.scope);
+
+        registration.addEventListener('updatefound', () => {
+          const newWorker = registration.installing;
+          newWorker.addEventListener('statechange', () => {
+            if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
+              console.log('[PWA] New version available! Refresh to update.');
+            }
+          });
+        });
+      })
+      .catch(error => {
+        console.log('[PWA] Service Worker registration failed:', error);
+      });
+  });
+}
+
+// Prompt user to install PWA (for browsers that support it)
+let deferredPrompt;
+window.addEventListener('beforeinstallprompt', (e) => {
+  console.log('[PWA] Install prompt available');
+  e.preventDefault();
+  deferredPrompt = e;
+  // Could show custom install button here if desired
+});
+
+// Track when user installs the app
+window.addEventListener('appinstalled', () => {
+  console.log('[PWA] BattleWords installed successfully!');
+  deferredPrompt = null;
+});
+</script>
+"""
+
+
+ocean_background_css = """
+<style>
+:root {
+  --water-deep: #0b2a4a;
+  --water-mid:  #0f3968;
+  --water-lite: #165ba8;
+  --water-sky:  #1d64c8;
+  --foam:       rgba(255,255,255,0.18);
+}
+
+.stAppHeader{
+    opacity:0.6;
+}
+
+.stApp {
+  margin: 0;
+  min-height: 100vh;
+  overflow: hidden;  /* prevent scrollbars from animated layers */
+  background-attachment: scroll;
+  position: relative;
+
+  /* Static base gradient */
+  background-image:
+    linear-gradient(180deg, var(--water-sky) 0%, var(--water-lite) 35%, var(--water-mid) 70%, var(--water-deep) 100%);
+  background-size: 100% 100%;
+  background-position: 50% 50%;
+
+  animation: none !important;
+  will-change: background-position;
+}
+
+/* Animated overlay waves (under bg layers) */
+.stApp::before {
+  content: "";
+  position: absolute;
+  inset: -10% -10%;
+  z-index: 0;
+  pointer-events: none;
+  background:
+    repeating-linear-gradient(0deg, rgba(255,255,255,0.10) 0 2px, transparent 2px 22px),
+    repeating-linear-gradient(90deg, rgba(255,255,255,0.06) 0 1px, transparent 1px 18px);
+  mix-blend-mode: screen;
+  opacity: 0.10;
+  /*animation: waveOverlayScroll 16s linear infinite;*/
+}
+.stIFrame {
+    margin-bottom:25px;
+}
+
+@keyframes waveOverlayScroll {
+  0%   { background-position:   0px   0px,   0px   0px; }
+  100% { background-position: -800px   0px,   0px -600px; }
+}
+
+/* Keep Streamlit content above background/overlay */
+.stApp > div { position: relative; z-index: 5; }
+
+/* Slower, more subtle animations */
+@keyframes oceanHighlight {
+  0%   { background-position: 50% 0%; }
+  50%  { background-position: 60% 8%; }
+  100% { background-position: 50% 0%; }
+}
+
+@keyframes oceanLong {
+  0%   { background-position: 0% 50%; }
+  100% { background-position: -100% 50%; }
+}
+
+@keyframes oceanMid {
+  0%   { background-position: 100% 50%; }
+  100% { background-position: 200% 50%; }
+}
+
+@keyframes oceanFine {
+  0%   { background-position: 0% 50%; }
+  100% { background-position: 100% 50%; }
+}
+
+/* Reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  .stApp, .stApp::before { animation: none; }
+}
+</style>
+"""
+
+def inject_ocean_layers() -> None:
+    st.markdown(
+        """
+        <style>
+          .bw-bg-container {
+            position: fixed;     /* fixed to viewport, not stApp */
+            inset: 0;
+            z-index: 1;          /* below content (z=5) but above ::before (z=0) */
+            pointer-events: none;
+            overflow: hidden;    /* clip children */
+          }
+          .bw-bg-layer {
+            position: absolute;
+            inset: 0;
+            width: 100vw;
+            height: 100vh;
+            pointer-events: none;
+          }
+          /* Explicit stacking order with slower animations */
+          .bw-bg-highlight { 
+            z-index: 11; 
+            background: radial-gradient(150% 100% at 50% -20%, rgba(255,255,255,0.10) 0%, transparent 60%); 
+            background-size: 150% 150%;  /* reduced from 300% */
+            /* animation: oceanHighlight 12s ease-in-out infinite; */ /* doubled from 6s */
+          }
+          .bw-bg-long { 
+            z-index: 12; 
+            background: repeating-linear-gradient(-6deg, rgba(255,255,255,0.08) 0px, rgba(255,255,255,0.08) 18px, rgba(0,0,0,0.04) 18px, rgba(0,0,0,0.04) 48px); 
+            background-size: 150% 150%;  /* reduced from 320% */
+            /* animation: oceanLong 36s linear infinite; */  /* doubled from 18s */
+            opacity: 0.2; 
+          }
+          .bw-bg-mid { 
+            z-index: 13; 
+            background: repeating-linear-gradient(-12deg, rgba(255,255,255,0.10) 0px, rgba(255,255,255,0.10) 10px, rgba(0,0,0,0.05) 10px, rgba(0,0,0,0.05) 26px); 
+            background-size: 150% 150%;  /* reduced from 260% */
+            /* animation: oceanMid 24s linear infinite; */  /* doubled from 12s */
+            opacity: 0.2; 
+          }
+          .bw-bg-fine { 
+            z-index: 14; 
+            background: repeating-linear-gradient(-18deg, var(--foam) 0px, var(--foam) 4px, transparent 4px, transparent 12px); 
+            background-size: 120% 120%;  /* reduced from 200% */
+            animation: oceanFine 14s linear infinite;  /* doubled from 7s */
+            opacity: 0.15; 
+          }
+        </style>
+        <div class="bw-bg-container">
+          <div class="bw-bg-layer bw-bg-highlight"></div>
+          <div class="bw-bg-layer bw-bg-long"></div>
+          <div class="bw-bg-layer bw-bg-mid"></div>
+          <div class="bw-bg-layer bw-bg-fine"></div>
+        </div>
+        """,
+        unsafe_allow_html=True,
+    )
+
+
+def inject_styles() -> None:
+    st.markdown(
+        """
+        <style>
+            /* Center main content and limit width */
+            # .stApp, body {
+            #     background: rgba(29, 100, 200, 0.5);
+            # }
+           .stMainBlockContainer {
+            max-width: 1100px;
+           }
+           .stHeading {
+                margin-bottom: -1.5rem !important;
+                margin-top: -1.5rem !important;
+                # font-size: 1.75rem !important; /* Title */
+                line-height: 1.1 !important;
+           }
+           #reveal-letters-in-cells-then-guess-the-words {
+            font-size: 16px !important; /* Subheader */
+            margin-top: .1rem !important;
+           }
+          /* Base grid cell visuals */
+          .bw-row { display: flex; gap: 0.1rem; flex-wrap: nowrap; min-height: 48px;}
+          .bw-cell {
+            width: 100%;
+            gap: 0.1rem;
+            aspect-ratio: 1 / 1;
+            line-height: 1.6;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            border: 1px solid #1d64c8;
+            border-radius: 0;
+            font-weight: 700;
+            user-select: none;
+            padding: 0.5rem 0.75rem;
+            font-size: 1.4rem;
+            min-height: 2.5rem;
+            min-width: 1.25em;
+            transition: background 0.2s ease, color 0.2s ease, border-color 0.2s ease;
+            background: #1d64c8;   /* Base cell color */
+            color: #FFFFFF;         /* Base text color for contrast */
+          }
+          /* Found letter cells */
+          .bw-cell.letter { background: #d7faff; color: #050057; }
+          /* Optional empty state if ever used */
+          .bw-cell.empty  { background: #3a3a3a; color: #ffffff;}
+          /* Completed word cells */
+          .bw-cell.bw-cell-complete { background: #050057 !important; color: #d7faff !important; }
+
+          /* Final score style */
+          .bw-final-score { color: #1ca41c !important; font-weight: 800; }
+          .stExpander {z-index: 10;width: 50%;}
+          div[data-testid="stToastContainer"], div[data-testid="stToast"] {
+            margin: 0 auto;
+          }
+
+          /* Make grid buttons square and fill their column */
+          div[data-testid="stButton"]{
+            margin: 0 auto;
+            text-align: center;
+          }
+          div[data-testid="stButton"] button { max-width: 100%; aspect-ratio: 16 / 11; min-height: 1.75rem; display: flex;}  
+          .st-key-new_game_btn > div[data-testid="stButton"] button, .st-key-sort_wordlist_btn > div[data-testid="stButton"] button, .st-key-filter_wordlist_btn > div[data-testid="stButton"] button { min-height: calc(100% + 20px) !important;}
+          /* div[data-testid="stButton"] button { max-width: 100%; aspect-ratio: 1 / 1; border-radius: 0; background: #1d64c8; color: #ffffff; font-weight: 700; padding: 0.5rem 0.75rem; min-height: 2.5rem; min-width: 2.5rem;} */
+          .st-key-new_game_btn, .st-key-sort_wordlist_btn, .st-key-filter_wordlist_btn, .st-key-settings_save_apply_btn, .st-key-settings_discard_btn { margin: 0 auto; aspect-ratio: unset; z-index:9999;}
+          .st-key-new_game_btn > div[data-testid="stButton"] button, .st-key-sort_wordlist_btn > div[data-testid="stButton"] button, .st-key-filter_wordlist_btn > div[data-testid="stButton"] button, .st-key-settings_save_apply_btn > div[data-testid="stButton"] button, .st-key-settings_discard_btn > div[data-testid="stButton"] button { aspect-ratio: unset; text-align:center; height: auto; width: 160px; border-radius:8px;}
+          
+
+          div[data-testid="column"], .st-emotion-cache-zh2fnc, .st-emotion-cache-1tj828o { width: auto !important; flex: 1 1 auto !important; min-width: 100% !important; max-width: 100% !important; border-radius:0;}
+          .st-emotion-cache-1permvm, .st-emotion-cache-1n6tfoc { gap:0.15rem !important; min-height: 2.5rem; min-width: 2.5rem;}          
+
+          .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, #a1a1a1, #ffffff, #a1a1a1, #666666); gap: 0.1rem !important; color: white; border-radius:15px; padding: 10px 10px 10px 5px; }
+          .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; }
+
+          /* grid adjustments */
+          @media (min-width: 560px){
+           div[data-testid="stButton"] button { max-width: 100%; aspect-ratio: 1 / 1; min-height: 40px !important;}           
+           .st-key-new_game_btn > div[data-testid="stButton"] button, .st-key-sort_wordlist_btn > div[data-testid="stButton"] button { min-height: calc(100% + 20px) !important;}
+           .st-emotion-cache-ckafi0 { gap:0.1rem !important; min-height: calc(100% + 20px) !important; aspect-ratio: 1 / 1; width: auto !important;  flex: 1 1 auto !important;  min-width: 100% !important;  max-width: 100% !important;}
+           /*.st-emotion-cache-1n6tfoc { aspect-ratio: 1 / 1; min-height: calc(100% + 20px) !important;}*/
+           .st-emotion-cache-1n6tfoc::before { min-height: calc(100% + 20px) !important; }
+
+          }
+          div[data-testid="stElementToolbarButtonContainer"], button[data-testid="stBaseButton-elementToolbar"], button[data-testid="stBaseButton-elementToolbar"]:hover {
+               display: none;
+          }
+
+          /* Mobile styles */
+          @media (max-width: 640px) {
+            .bw-cell, div[data-testid="stButton"] button, .st-emotion-cache-1permvm {min-width: 1.5rem; min-height:40px;}
+            #bw-main-anchor + div[data-testid="stHorizontalBlock"] { flex-direction: column-reverse !important; width: 100% !important; max-width: 100vw !important; }
+            #bw-main-anchor + div[data-testid="stHorizontalBlock"] > div[data-testid="column"] { width: 100% !important; min-width: 100% !important; max-width: 100% !important; flex: 1 1 100% !important; }
+            .bw-grid-row-anchor + div[data-testid="stHorizontalBlock"] { flex-wrap: nowrap !important; overflow-x: auto !important; margin: 2px 0 !important; }
+            .st-emotion-cache-17i4tbh, .st-emotion-cache-1yoilpv { min-width: calc(8.33333% - 1rem); }            
+          }
+
+          .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; }
+          .shiny-border { position: relative; padding: 10px; 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; }
+          .shiny-border:hover::before { left: 100%; }
+
+          .bw-radio-group { display:flex; align-items:flex-start; gap: 5px; flex-flow: row; min-height: 92px;}
+          .bw-radio-item { display:flex; flex-direction:column; align-items:center; gap:6px; text-align:center;}
+          .bw-radio-circle { width: 45px; height: 45px; border-radius: 50%; border: 4px solid; background: rgba(255,255,255,0.06); display: grid; place-items: center; color:#fff; font-weight:700; }
+          .bw-radio-circle .dot { width: 14px; height: 14px; border-radius: 50%; background:#777; box-shadow: inset 0 0 0 2px rgba(255,255,255,0.25); }
+          .bw-radio-circle.active.hit { background: linear-gradient(135deg, rgba(0,255,127,0.18), rgba(0,128,64,0.38)); }
+          .bw-radio-circle.active.hit .dot { background:#20d46c; box-shadow: 0 0 10px rgba(32,212,108,0.85); }
+          .bw-radio-circle.active.miss { background: linear-gradient(135deg, rgba(255,0,0,0.18), rgba(128,0,0,0.38)); }
+          .bw-radio-circle.active.miss .dot { background:#ff4b4b; box-shadow: 0 0 10px rgba(255,75,75,0.85); }
+          .bw-radio-caption { font-size: 0.8rem; color:#fff; opacity:0.85; letter-spacing:0.5px; }
+          @media (max-width:1000px) and (min-width:641px) {
+            .bw-radio-group { flex-wrap:wrap; gap: 5px; margin-bottom: 5px;}
+            .bw-radio-item {margin: 0 auto;}
+          }
+          @media (max-width:640px) {
+            .bw-radio-item { margin:unset;}
+          }
+
+          /* Make the sidebar scrollable */
+          section[data-testid="stSidebar"] {
+              max-height: 100vh;
+              overflow-y: auto;
+              overflow-x: hidden;
+              scrollbar-width: thin;
+              scrollbar-color: transparent transparent;
+              opacity:0.75;
+          }
+
+         .st-emotion-cache-wp60of {
+             width: 720px;
+             position: absolute;     
+             max-width:100%;
+          }
+         .stImage {max-width:240px;}
+         [id^="text_input"] {
+          background-color:#fff;
+          color:#000;
+          caret-color:#333;}
+        
+         @media (min-width:720px) {         
+          .st-emotion-cache-wp60of {
+            left: calc(calc(100% - 720px) / 2);
+          }
+         }
+
+          /* Helper to absolutely/fixed position Streamlit component wrapper when showing modal */
+          .bw-component-abs { position: fixed !important; inset: 0 !important; z-index: 99999 !important; width: 100vw !important; height: 100vh !important; margin: 0 !important; padding: 0 !important; }
+          /* Generic hide utility */
+          .hide { display: none !important; pointer-events: none !important; }
+        </style>
+        """,
+        unsafe_allow_html=True,
+    )
+
+# --- Footer Navigation ---
 def render_footer(current_page: str = "play") -> None:
     """Render footer navigation.
 
@@ -88,3 +557,52 @@ def render_footer(current_page: str = "play") -> None:
         """,
         unsafe_allow_html=True,
     )
+
+
+# --- Spinner Overlay ---
+def show_spinner(message: str = "Loading..."):
+    """
+    Show a full-page overlay with a wrdler.gif spinner and optional message.
+
+    Args:
+        message (str): Message to display with the spinner.
+    """
+    # gif_path = os.path.join(os.path.dirname(__file__), "assets", "wrdler.gif")
+    # gif_data = None
+    # if os.path.exists(gif_path):
+    #     with open(gif_path, "rb") as f:
+    #         gif_data = base64.b64encode(f.read()).decode("utf-8")
+    #     img_tag = f'<img src="data:image/gif;base64,{gif_data}" alt="Loading..." width="192" height="192" />'
+    # else:
+    #     img_tag = '<div style="width:80px;height:80px;background:#eee;border-radius:16px;"></div>'
+
+    st.markdown(
+        f'''
+        <style>
+        .bw-spinner-overlay {{
+            position: fixed; z-index: 99999; top: 0; left: 0; width: 100vw; height: 100vh;
+            # transition: background 0.2s ease, color 0.2s ease, border-color 0.2s ease;
+            background: rgba(11,42,74,1.0); display: flex; align-items: center; justify-content: center;            
+        }}
+        .bw-spinner-img {{
+            width: 150px; height: 150px; border-radius: 16px; box-shadow: 0 0 8px #1d64c8;
+            background: #fff; display: flex; align-items: center; justify-content: center;
+        }}
+        .modal-spinner-inner {{
+            background: rgba(255,255,255,0.75); padding: 1rem 2rem; border-radius: 1rem;
+            box-shadow: 0 0 16px #1d64c8;
+            font-size: 1.5rem; color: #1d64c8;
+        }}
+        .bw-spinner-msg {{
+            color: #1d64c8; font-size: 1.2rem; margin-top: 1.5rem; text-align: center; font-weight: 600;
+        }}
+        </style>
+        <div class="bw-spinner-overlay">
+            <div class="modal-spinner-inner" style="display:flex; flex-direction:column; align-items:center;">
+                <div class="bw-spinner-img stImage"><img src="/app/static/wrdler.gif" alt="Loading..." width="192" height="192" /></div>
+                <div class="bw-spinner-msg">{message}</div>
+            </div>
+        </div>
+        ''',
+        unsafe_allow_html=True
+    )

battlewords/words/classic.txt

@@ -45,7 +45,6 @@ COIN
 COPY
 CORN
 COST
-COST
 CUTE
 DASH
 DATE

claude.md

@@ -3,8 +3,8 @@
 ## Project Overview
 BattleWords is a vocabulary learning game inspired by Battleship mechanics, built with Streamlit and Python 3.12. Players reveal cells on a 12x12 grid to discover hidden words and earn points for strategic guessing.
 
-**Current Version:** 0.2.30 (Stable - PWA, Challenge Mode & Remote Storage)
-**Last Updated:** 2026-01-12
+**Current Version:** 0.2.31 (Stable - PWA, Challenge Mode & Remote Storage)
+**Last Updated:** 2026-01-13
 **Next Version:** 0.3.0 (In Development - Wrdler improvements)
 **Repository:** https://github.com/Oncorporation/BattleWords.git
 **Live Demo:** https://huggingface.co/spaces/Surn/BattleWords
@@ -49,8 +49,8 @@ The following non-gameplay improvements from Wrdler are being ported to BattleWo
 - ⏳ Leaderboard browsing UI (Today/Daily/Weekly/History)
 
 ### Storage/Utilities
-- ⏳ HF repo folder listing helper
-- ⏳ HF repo list files in folder helper
+- ✅ HF repo folder listing helper
+- ✅ HF repo list files in folder helper
 
 ### Version & Diagnostics
 - ✅ Ported version_info.py to modules
@@ -62,26 +62,15 @@ The following non-gameplay improvements from Wrdler are being ported to BattleWo
 
 ---
 
-## Recent Changes & Branch Status
-
-**Latest (v0.2.28):**
-- Progressive Web App (PWA) support
-  - Added `service worker` and `manifest.json`
-  - Basic offline caching of static assets
-  - INSTALL_GUIDE.md added with install steps
-  - No gameplay logic changes
-- **UI Update:**
-  - Leaderboard navigation is now in the footer menu, not the sidebar
-  - Footer navigation links to Leaderboard, Play, and Settings pages
-  - Leaderboard page routing uses query parameters and custom navigation links
-  - Game over dialog integrates leaderboard submission and displays qualification results
-
-**Previous (v0.2.27):**
-- New setting: "Show Challenge Share Links" (default OFF)
-  - Header Challenge Mode banner hides the "Share this challenge" link when disabled
-  - Game Over dialog still lets you submit or create a challenge, but hides the generated share URL when disabled (shows a success message instead)
-  - Setting is stored in Streamlit session state and preserved across "New Game"
-  - No changes to `logic.py` or `game_storage.py`; this is a UI-only visibility feature
+## Summary of Recent Changes (v0.2.31)
+- Updated README.md with new Streamlit SDK (1.52.1) and Python (3.12.8).
+- Incremented version to 0.2.31 in `__init__.py` and `pyproject.toml`.
+- Enhanced `audio.py` with error handling and smoother playback.
+- Added `validate_puzzle` and `filter_word_file` functions in `generator.py`.
+- Introduced new constants and `load_settings` in `constants.py`.
+- Improved settings page with wordlist controls and audio settings.
+- Refined UI in `ui.py` with compact layouts and performance optimizations.
+- Modularized helpers in `ui_helpers.py` and reintroduced PWA support.
 
 ## Core Gameplay
 - 12x12 grid with 6 hidden words (2×4-letter, 2×5-letter, 2×6-letter)

pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "battlewords"
-version = "0.2.30"
+version = "0.2.31"
 description = "BattleWords vocabulary game with game sharing via shortened game_id URL referencing server-side JSON settings"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"
 dependencies = [
-    "streamlit>=1.51.0",
+    "streamlit>=1.52.1",
     "matplotlib>=3.8",
     "requests>=2.31.0",
 ]

specs/specs.md

@@ -1,5 +1,8 @@
 # Battlewords Game Requirements (specs.md)
 
+**Current Version:** 0.2.31
+**Last Updated:** 2026-01-13
+
 ## Overview
 Battlewords is inspired by the classic Battleship game, but uses words instead of ships. The objective is to discover hidden words on a grid, earning points for strategic guessing before all letters are revealed.
 
@@ -56,6 +59,18 @@ The following non-gameplay improvements from Wrdler are being ported to BattleWo
 
 ---
 
+## Summary of Recent Changes (v0.2.31)
+- Updated README.md with new Streamlit SDK (1.52.1) and Python (3.12.8).
+- Incremented version to 0.2.31 in `__init__.py` and `pyproject.toml`.
+- Enhanced `audio.py` with error handling and smoother playback.
+- Added `validate_puzzle` and `filter_word_file` functions in `generator.py`.
+- Introduced new constants and `load_settings` in `constants.py`.
+- Improved settings page with wordlist controls and audio settings.
+- Refined UI in `ui.py` with compact layouts and performance optimizations.
+- Modularized helpers in `ui_helpers.py` and reintroduced PWA support.
+
+---
+
 ## Game Board
 - 12 x 12 grid.
 - Six hidden words:

specs/upgrade.md

@@ -1,5 +1,18 @@
 # Upgrade checklist: porting useful `wrdler` improvements into `battlewords`
 
+**Current Version:** 0.2.31
+**Last Updated:** 2026-01-13
+
+## Summary of Recent Changes (v0.2.31)
+- Updated README.md with new Streamlit SDK (1.52.1) and Python (3.12.8).
+- Incremented version to 0.2.31 in `__init__.py` and `pyproject.toml`.
+- Enhanced `audio.py` with error handling and smoother playback.
+- Added `validate_puzzle` and `filter_word_file` functions in `generator.py`.
+- Introduced new constants and `load_settings` in `constants.py`.
+- Improved settings page with wordlist controls and audio settings.
+- Refined UI in `ui.py` with compact layouts and performance optimizations.
+- Modularized helpers in `ui_helpers.py` and reintroduced PWA support.
+
 ## Context summary (for a fresh chat)
 
 - **Goal:** Bring over non-gameplay improvements from `wrdler` into `battlewords`—primarily **leaderboards**, **settings management**, **UI/navigation**, and **remote storage helpers**.
@@ -34,9 +47,10 @@ Scope: only non-gameplay changes (leaderboards, settings, UI/UX, storage/utiliti
 
 ## UI/UX Improvements (from Wrdler)
 
-- [ ] Combine "Your Guess" and guess result into a single UI element, as in Wrdler.
-- [ ] Shrink space in scoreboard for a more compact screen layout.
+- [x] Combine "Your Guess" and guess result into a single UI element, as in Wrdler.
+- [x] Shrink space in scoreboard for a more compact screen layout.
 - [x] Radar graphic size reduced to 240px to save processing and load time.
+- [x] Remove waves from background for cleaner look and better performance.
 
 ---