v0.2.6

Refactor settings and update to version 0.2.6

Refactored the settings logic by moving sidebar controls to a dedicated `settings_page.py` file, improving modularity and user experience. Added routing for the new "Settings" page and updated the footer navigation.

Centralized audio handling with a new `_handle_audio` function for consistent behavior across pages. Simplified and cleaned up redundant code in `ui.py`.

Updated version to `0.2.6` across all relevant files, including `CLAUDE.md`, `GAMEPLAY_GUIDE.md`, `README.md`, and `pyproject.toml`. Enhanced changelogs and documentation to reflect new features.

Introduced a paywall specification (`paywall.md`) for future subscription-based access. Added detailed plans for settings refactoring in `settings.md`.

Improved maintainability and prepared the app for monetization while enhancing the user interface and overall functionality.

CLAUDE.md

@@ -8,11 +8,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.4
+**Current Version:** 0.2.6
 **Repository:** https://github.com/Oncorporation/Wrdler.git
 **Branch:** AI (working branch)
 
-## Current Features (v0.2.4)
+## Current Features (v0.2.6)
 
 ### Core Gameplay
 - 8x6 grid with 6 hidden words (one per row, horizontal only)

GAMEPLAY_GUIDE.md

@@ -1,5 +1,5 @@
 # Wrdler Gameplay Guide
-**Version:** 0.0.2
+**Version:** 0.2.6
 **Last Updated:** 2025-01-31
 
 ## Welcome to Wrdler!

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
@@ -25,7 +25,7 @@ thumbnail: >-
 
 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.4
+**Current Version:** v0.2.6
 
 ## Key Differences from BattleWords
 
@@ -242,7 +242,7 @@ All test files must be placed in the `/tests` folder. This ensures a clean proje
 
 ## Changelog
 
-### v0.2.4 (Current) ✅
+### v0.2.6 (Current) ✅
 **Word List Filtering**
 - ✅ Added "Filter Wordlist" button to sidebar
 - ✅ Filters words against `assets/filter.txt` blocklist

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wrdler"
-version = "0.2.2"
+version = "0.2.6"
 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"
@@ -23,7 +23,6 @@ include-package-data = true
 
 [tool.setuptools.packages.find]
 where = [""]
-include = ["wrdler*"]
 
 [tool.setuptools.package-data]
 "wrdler.words" = ["*.txt"]

specs/leaderboard_spec.md

@@ -1,7 +1,7 @@
 # Wrdler Leaderboard System Specification
 
 **Document Version:** 1.4.0
-**Project Version:** 0.2.0
+**Project Version:** 0.2.6
 **Author:** GitHub Copilot
 **Last Updated:** 2025-12-08
 **Status:** ✅ Implemented and Documented

specs/paywall.md

@@ -0,0 +1,64 @@
+# Paywall Integration Specification
+
+This document outlines the plan to integrate `st-paywall` into the Wrdler application to enable subscription-based access.
+
+## 1. Dependencies
+
+Add `st-paywall` to the project dependencies.
+
+- **File**: `pyproject.toml`
+- **Action**: Add `st-paywall` to the `dependencies` list.
+
+## 2. Configuration
+
+Configure the payment provider (Stripe or Buy Me A Coffee) in Streamlit secrets.
+
+- **File**: `.streamlit/secrets.toml` (User needs to create this if not exists)
+- **Content**:
+    ```toml
+    [stripe]
+    api_key = "sk_live_..."
+    link = "https://buy.stripe.com/..."
+    # OR
+    [bmac]
+    api_key = "..."
+    link = "https://www.buymeacoffee.com/..."
+    ```
+    *Note: `st-paywall` expects specific keys. Refer to documentation for exact structure.*
+
+## 3. Code Integration
+
+Integrate the authentication and subscription check into the main UI flow.
+
+- **File**: `wrdler/ui.py`
+- **Import**: `from st_paywall import add_auth`
+- **Placement**:
+    - The `add_auth` function should be called early in the `run_app` function or before rendering sensitive content.
+    - It handles the login UI and subscription check.
+
+### Integration Strategy
+
+We will add a "Premium" toggle or check, or enforce it for the whole app depending on requirements. For now, we will document how to gate the entire app or specific premium features (like AI Wordlist generation).
+
+**Option A: Gate Entire App**
+Call `add_auth(required=True)` at the start of `run_app`.
+
+**Option B: Gate Premium Features**
+Call `add_auth(required=False)` to show the login/subscribe sidebar but allow free access. Then check `st.session_state.user_subscribed` (or similar provided by the library) before enabling features like:
+- AI Wordlist Generation
+- Challenge Mode creation
+
+## 4. Implementation Plan
+
+1.  **Update `pyproject.toml`**: Add `st-paywall`.
+2.  **Update `wrdler/ui.py`**:
+    - Import `add_auth`.
+    - Insert `add_auth(...)` call in `run_app` or `_render_sidebar`.
+    - (Optional) Wrap premium features with subscription checks.
+
+## 5. Testing
+
+- Verify that the login button appears.
+- Verify that non-subscribed users are prompted to subscribe.
+- Verify that subscribed users can access the content.
+- Test with `testing_mode = true` in secrets.

specs/requirements.md

@@ -1,5 +1,5 @@
 # Wrdler: Implementation Requirements
-**Version:** 0.2.4
+**Version:** 0.2.6
 **Status:** Production Ready - Leaderboards Implemented
 **Last Updated:** 2025-12-08
 

specs/settings.md

@@ -0,0 +1,65 @@
+# Settings Page Refactoring Plan
+
+## Goal
+Move the sidebar configuration controls (`_render_sidebar`) from `wrdler/ui.py` to a dedicated Settings page (`wrdler/settings_page.py`), accessible via the footer navigation.
+
+## Files to Create
+1.  `wrdler/settings_page.py`
+
+## Files to Modify
+1.  `wrdler/ui.py`
+
+## Detailed Steps
+
+### 1. Create `wrdler/settings_page.py`
+This file will encapsulate the rendering logic for the settings.
+
+-   **Imports**:
+    -   `streamlit as st`
+    -   `os`
+    -   `time`
+    -   From `wrdler.word_loader`: `get_wordlist_files`, `get_wordlist_info`
+    -   From `wrdler.generator`: `sort_word_file`, `filter_word_file`
+    -   From `wrdler.audio`: `get_audio_tracks`, `_inject_audio_control_sync`
+    -   From `wrdler.version_info`: `versions_html`
+
+-   **Functions**:
+    -   `render_settings_page(new_game_callback)`:
+        -   Renders the title "Settings".
+        -   Contains the logic previously in `_render_sidebar` (Game Mode, Wordlist Controls, Grid Options, Audio Controls).
+        -   **Important**: Does *not* include `_mount_background_audio` (this will be global).
+        -   Uses `st.container` or main layout instead of `st.sidebar`.
+        -   Accepts `new_game_callback` to trigger a game reset when settings change.
+    -   `_sort_wordlist(filename)`: Moved from `ui.py`.
+    -   `_filter_wordlist(filename)`: Moved from `ui.py`.
+    -   `_filter_results_dialog`: Moved from `ui.py` (if used by `_filter_wordlist`).
+    -   Local callbacks `_on_wordlist_change` and `_on_ai_generate` that utilize `new_game_callback`.
+
+### 2. Modify `wrdler/ui.py`
+
+-   **Extract Audio Logic**:
+    -   Create a helper function `_handle_audio()` that contains the audio initialization and mounting logic previously in `_render_sidebar`.
+    -   This ensures audio persists across pages.
+
+-   **Update `run_app()`**:
+    -   Call `_handle_audio()` at the top level (before page routing).
+    -   Add routing logic for `page="settings"`:
+        -   Import `render_settings_page`.
+        -   Render background.
+        -   Call `render_settings_page(_on_game_option_change)`.
+        -   Render footer with `current_page="settings"`.
+        -   Return (stop execution of main game).
+    -   Remove `_render_sidebar()` call.
+
+-   **Update `_render_footer()`**:
+    -   Add a link to `?page=settings` with label "?? Settings".
+    -   Highlight it when `current_page="settings"`.
+
+-   **Cleanup**:
+    -   Remove `_render_sidebar` function.
+    -   Remove `_sort_wordlist`, `_filter_wordlist` (moved to settings page).
+
+## Implementation Notes
+-   **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".

specs/specs.md

@@ -1,5 +1,5 @@
 # Wrdler Game Specifications (specs.md)
-**Version:** 0.2.4
+**Version:** 0.2.6
 **Status:** Production Ready - Leaderboards Implemented
 **Last Updated:** 2025-12-08
 

wrdler/__init__.py

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

wrdler/settings_page.py

@@ -0,0 +1,347 @@
+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
+
+def _sort_wordlist(filename, new_game_callback):
+    import os
+    import time
+
+    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_callback()
+
+def _filter_results_content(count: int, words: list[str], filename: str):
+    st.success(f"Removed {count} words from {filename}")
+    st.markdown("### Removed Words")
+    st.text_area("List", value="\n".join(words), height=200, disabled=True)
+    if st.button("Close", key="close_filter_dialog"):
+        st.rerun()
+
+# Prefer st.dialog/experimental_dialog; fallback to st.modal if unavailable
+_Dialog = getattr(st, "dialog", getattr(st, "experimental_dialog", None))
+if _Dialog:
+    @_Dialog("Filter Results")
+    def _filter_results_dialog(count, words, filename):
+        _filter_results_content(count, words, filename)
+else:
+    def _filter_results_dialog(count, words, filename):
+        modal_ctx = getattr(st, "modal", None)
+        if callable(modal_ctx):
+            with modal_ctx("Filter Results"):
+                _filter_results_content(count, words, filename)
+        else:
+            st.info(f"Removed {count} words from {filename}")
+            st.text_area("Removed Words", value="\n".join(words), height=200)
+
+def _filter_wordlist(filename):
+    filter_path = os.path.join(os.path.dirname(__file__), "assets", "filter.txt")
+    words_path = os.path.join(os.path.dirname(__file__), "words", filename)
+    
+    if not os.path.exists(filter_path):
+        st.error("Filter file not found (wrdler/assets/filter.txt).")
+        return
+
+    count, removed_words = filter_word_file(filter_path, words_path)
+    
+    if count > 0:
+        _filter_results_dialog(count, removed_words, filename)
+    else:
+        st.info(f"No words removed from {filename}.")
+
+def render_settings_page(new_game_callback):
+    st.header("SETTINGS")        
+
+    st.header("Game Mode")
+    game_modes = ["classic", "easy", "too easy"]
+    default_mode = "classic"
+    if "game_mode" not in st.session_state:
+        st.session_state.game_mode = default_mode
+    current_mode = st.session_state.game_mode
+    st.selectbox(
+        "Select game mode",
+        options=game_modes,
+        index=game_modes.index(current_mode) if current_mode in game_modes else 0,
+        key="game_mode",
+        on_change=new_game_callback,
+    )
+
+    st.header("Wordlist Controls")
+    
+    # Initialize AI mode settings
+    if "use_ai_wordlist" not in st.session_state:
+        st.session_state.use_ai_wordlist = False
+    if "ai_topic" not in st.session_state:
+        st.session_state.ai_topic = "English"
+    
+    wordlist_files = get_wordlist_files()
+    
+    # Add AI Generated option to file list
+    wordlist_options = ["AI Generated"] + wordlist_files if wordlist_files else ["AI Generated"]
+    
+    def _on_wordlist_change():
+        selected = st.session_state.get("wordlist_selector")
+        if selected == "AI Generated":
+            st.session_state.use_ai_wordlist = True
+            if "ai_topic" not in st.session_state:
+                st.session_state.ai_topic = "English"
+        else:
+            st.session_state.use_ai_wordlist = False
+            st.session_state.selected_wordlist = selected
+            new_game_callback()
+
+    def _on_ai_generate():
+        new_game_callback()
+
+    if wordlist_files:
+        # Determine current selection index
+        if st.session_state.get("use_ai_wordlist", False):
+            current_index = 0  # AI Generated
+        elif st.session_state.get("selected_wordlist") in wordlist_files:
+            current_index = wordlist_options.index(st.session_state.selected_wordlist)
+        else:
+            # Default to first file
+            st.session_state.selected_wordlist = wordlist_files[0]
+            st.session_state.use_ai_wordlist = False
+            current_index = 1
+
+        # Wordlist selector
+        selected = st.selectbox(
+            "Select list",
+            options=wordlist_options,
+            index=current_index,
+            format_func=lambda f: f if f == "AI Generated" else f.rsplit(".", 1)[0],
+            key="wordlist_selector",
+            on_change=_on_wordlist_change,
+        )
+        
+        # Show topic input if AI mode selected
+        if selected == "AI Generated":
+            st.session_state.use_ai_wordlist = True
+            
+            # Topic input and Generate button in columns
+            topic_col, gen_col = st.columns([3, 1], gap="small")
+            
+            with topic_col:
+                st.text_input(
+                    "Topic",
+                    value=st.session_state.ai_topic,
+                    key="ai_topic",
+                    placeholder="e.g., Ocean Life, Space, History",
+                    help="Enter a topic for AI-generated words",
+                    # Remove on_change to prevent automatic generation
+                )
+            
+            with gen_col:
+                # Add custom CSS for the generate button
+                st.markdown(
+                    """
+                    <style>
+                    .st-key-ai_generate_btn {
+                        margin-top: 1.85rem;  /* Align with text input */
+                    }
+                    .st-key-ai_generate_btn button {
+                        aspect-ratio: auto !important;
+                        height: auto !important;
+                        padding: 0.5rem 0.75rem !important;
+                    }
+                    </style>
+                    """,
+                    unsafe_allow_html=True,
+                )
+                st.button(
+                    "🎲",
+                    key="ai_generate_btn",
+                    help="Generate wordlist from topic",
+                    on_click=_on_ai_generate,
+                    use_container_width=True,
+                )
+            
+            # Display wordlist info below topic input
+            info_text = get_wordlist_info(
+                use_ai=True,
+                ai_topic=st.session_state.ai_topic
+            )
+            if info_text:
+                st.caption(info_text)
+        else:
+            st.session_state.use_ai_wordlist = False
+            st.session_state.selected_wordlist = selected
+            
+            # Display wordlist info below selection
+            info_text = get_wordlist_info(
+                use_ai=False,
+                selected_file=selected
+            )
+            if info_text:
+                st.caption(info_text)
+
+        # Only show Sort button for file-based wordlists
+        if not st.session_state.use_ai_wordlist:
+            if st.button("Sort Wordlist", width=125, key="sort_wordlist_btn"):
+                _sort_wordlist(st.session_state.selected_wordlist, new_game_callback)
+            if st.button("Filter Wordlist", width=125, key="filter_wordlist_btn"):
+                _filter_wordlist(st.session_state.selected_wordlist)
+    else:
+        st.info("No word lists found in words/ directory. Using AI or built-in fallback.")
+        # Force AI mode if no files available
+        st.session_state.use_ai_wordlist = True
+        
+        # Topic input and Generate button in columns
+        topic_col, gen_col = st.columns([3, 1], gap="small")
+        
+        with topic_col:
+            st.text_input(
+                "Topic",
+                value=st.session_state.ai_topic,
+                key="ai_topic",
+                placeholder="e.g., Ocean Life, Space, History",
+                help="Enter a topic for AI-generated words",
+                # Remove on_change to prevent automatic generation
+            )
+        
+        with gen_col:
+            # Add custom CSS for the generate button
+            st.markdown(
+                """
+                <style>
+                .st-key-ai_generate_btn {
+                    margin-top: 1.85rem;  /* Align with text input */
+                }
+                .st-key-ai_generate_btn button {
+                    aspect-ratio: auto !important;
+                    height: auto !important;
+                    padding: 0.5rem 0.75rem !important;
+                }
+                </style>
+                """,
+                unsafe_allow_html=True,
+            )
+            st.button(
+                "🎲",
+                key="ai_generate_btn",
+                help="Generate wordlist from topic",
+                on_click=_on_ai_generate,
+                use_container_width=True,
+            )
+        
+        # Display wordlist info below topic input
+        info_text = get_wordlist_info(
+            use_ai=True,
+            ai_topic=st.session_state.ai_topic
+        )
+        if info_text:
+            st.caption(info_text)
+    
+    # Add Show Grid ticks option
+    if "show_grid_ticks" not in st.session_state:
+        st.session_state.show_grid_ticks = False
+    st.checkbox("Show Grid ticks", value=st.session_state.show_grid_ticks, key="show_grid_ticks")
+    
+    # Add Spacer option
+    spacer_options = [0,1,2]
+    if "spacer" not in st.session_state:
+        st.session_state.spacer = 1
+    st.selectbox(
+        "Spacer (space between words)",
+        options=spacer_options,
+        index=spacer_options.index(st.session_state.spacer),
+        key="spacer",
+        on_change=new_game_callback,  # add callback
+    )
+
+    # Add Show Incorrect Guesses option - now enabled by default
+    if "show_incorrect_guesses" not in st.session_state:
+        st.session_state.show_incorrect_guesses = True
+    st.checkbox("Show incorrect guesses", value=st.session_state.show_incorrect_guesses, key="show_incorrect_guesses")
+
+    # NEW: Add Show Challenge Share Links option - default ON
+    if "show_challenge_share_links" not in st.session_state:
+        st.session_state.show_challenge_share_links = True
+    st.checkbox("Show Challenge Share Links", value=st.session_state.show_challenge_share_links, key="show_challenge_share_links")
+    
+    # NEW: Initialize Enable Free Letters (default OFF)
+    if "enable_free_letters" not in st.session_state:
+        st.session_state.enable_free_letters = False
+    st.checkbox("Enable Free Letters (2 per game)", value=st.session_state.enable_free_letters, key="enable_free_letters")
+
+    # Audio settings
+    st.header("Audio")
+    tracks = get_audio_tracks()
+    st.caption(f"{len(tracks)} audio file{'s' if len(tracks) != 1 else ''} found in wrdler/assets/audio/music")
+
+    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
+    # --- Add sound effects volume ---
+    if "effects_volume" not in st.session_state:
+        st.session_state.effects_volume = 25
+    # --- Add enable sound effects (default OFF) ---
+    if "enable_sound_effects" not in st.session_state:
+        st.session_state.enable_sound_effects = False
+    st.checkbox("Enable Sound Effects", value=st.session_state.enable_sound_effects, key="enable_sound_effects")
+
+    enabled = st.checkbox("Enable music", value=st.session_state.music_enabled, key="music_enabled")
+
+    st.slider(
+        "Volume",
+    0,
+    100,
+        value=int(st.session_state.music_volume),
+        step=1,
+        key="music_volume",
+        disabled=not (enabled and bool(tracks)),
+        )
+
+            # --- Add sound effects volume slider ---
+    st.slider(
+                "Sound Effects Volume",
+    0,
+    100,
+        value=int(st.session_state.effects_volume),
+        step=1,
+        key="effects_volume",
+        )
+
+    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.")
+
+    _inject_audio_control_sync()
+    st.markdown(versions_html(), unsafe_allow_html=True)

wrdler/ui.py

@@ -30,6 +30,7 @@ from .audio import (
 from .game_storage import load_game_from_sid, save_game_to_hf, get_shareable_url, add_user_result_to_game
 from .modules.constants import APP_SETTINGS
 from .leaderboard import submit_score_to_all_leaderboards
+from .settings_page import render_settings_page
 
 st.set_page_config(initial_sidebar_state="collapsed")
 
@@ -614,12 +615,7 @@ border-radius: 50% !important;
 
           /* 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;
+              display: none;
           }
 
          .st-emotion-cache-wp60of {
@@ -993,279 +989,30 @@ def _render_header():
 
     inject_styles()
 
-def _render_sidebar():
-    with st.sidebar:
-        st.header("SETTINGS")        
-
-        st.header("Game Mode")
-        game_modes = ["classic", "easy", "too easy"]
-        default_mode = "classic"
-        if "game_mode" not in st.session_state:
-            st.session_state.game_mode = default_mode
-        current_mode = st.session_state.game_mode
-        st.selectbox(
-            "Select game mode",
-            options=game_modes,
-            index=game_modes.index(current_mode) if current_mode in game_modes else 0,
-            key="game_mode",
-            on_change=_on_game_option_change,
-        )
-
-        st.header("Wordlist Controls")
-        
-        # Initialize AI mode settings
-        if "use_ai_wordlist" not in st.session_state:
-            st.session_state.use_ai_wordlist = False
-        if "ai_topic" not in st.session_state:
-            st.session_state.ai_topic = "English"
-        
-        wordlist_files = get_wordlist_files()
-        
-        # Add AI Generated option to file list
-        wordlist_options = ["AI Generated"] + wordlist_files if wordlist_files else ["AI Generated"]
-        
-        if wordlist_files:
-            # Determine current selection index
-            if st.session_state.get("use_ai_wordlist", False):
-                current_index = 0  # AI Generated
-            elif st.session_state.get("selected_wordlist") in wordlist_files:
-                current_index = wordlist_options.index(st.session_state.selected_wordlist)
-            else:
-                # Default to first file
-                st.session_state.selected_wordlist = wordlist_files[0]
-                st.session_state.use_ai_wordlist = False
-                current_index = 1
-
-            # Wordlist selector
-            selected = st.selectbox(
-                "Select list",
-                options=wordlist_options,
-                index=current_index,
-                format_func=lambda f: f if f == "AI Generated" else f.rsplit(".", 1)[0],
-                key="wordlist_selector",
-                on_change=_on_wordlist_change,
-            )
-            
-            # Show topic input if AI mode selected
-            if selected == "AI Generated":
-                st.session_state.use_ai_wordlist = True
-                
-                # Topic input and Generate button in columns
-                topic_col, gen_col = st.columns([3, 1], gap="small")
-                
-                with topic_col:
-                    st.text_input(
-                        "Topic",
-                        value=st.session_state.ai_topic,
-                        key="ai_topic",
-                        placeholder="e.g., Ocean Life, Space, History",
-                        help="Enter a topic for AI-generated words",
-                        # Remove on_change to prevent automatic generation
-                    )
-                
-                with gen_col:
-                    # Add custom CSS for the generate button
-                    st.markdown(
-                        """
-                        <style>
-                        .st-key-ai_generate_btn {
-                            margin-top: 1.85rem;  /* Align with text input */
-                        }
-                        .st-key-ai_generate_btn button {
-                            aspect-ratio: auto !important;
-                            height: auto !important;
-                            padding: 0.5rem 0.75rem !important;
-                        }
-                        </style>
-                        """,
-                        unsafe_allow_html=True,
-                    )
-                    st.button(
-                        "🎲",
-                        key="ai_generate_btn",
-                        help="Generate wordlist from topic",
-                        on_click=_on_ai_generate,
-                        use_container_width=True,
-                    )
-                
-                # Display wordlist info below topic input
-                info_text = get_wordlist_info(
-                    use_ai=True,
-                    ai_topic=st.session_state.ai_topic
-                )
-                if info_text:
-                    st.caption(info_text)
-            else:
-                st.session_state.use_ai_wordlist = False
-                st.session_state.selected_wordlist = selected
-                
-                # Display wordlist info below selection
-                info_text = get_wordlist_info(
-                    use_ai=False,
-                    selected_file=selected
-                )
-                if info_text:
-                    st.caption(info_text)
-
-            # Only show Sort button for file-based wordlists
-            if not st.session_state.use_ai_wordlist:
-                if st.button("Sort Wordlist", width=125, key="sort_wordlist_btn"):
-                    _sort_wordlist(st.session_state.selected_wordlist)
-                if st.button("Filter Wordlist", width=125, key="filter_wordlist_btn"):
-                    _filter_wordlist(st.session_state.selected_wordlist)
-        else:
-            st.info("No word lists found in words/ directory. Using AI or built-in fallback.")
-            # Force AI mode if no files available
-            st.session_state.use_ai_wordlist = True
-            
-            # Topic input and Generate button in columns
-            topic_col, gen_col = st.columns([3, 1], gap="small")
-            
-            with topic_col:
-                st.text_input(
-                    "Topic",
-                    value=st.session_state.ai_topic,
-                    key="ai_topic",
-                    placeholder="e.g., Ocean Life, Space, History",
-                    help="Enter a topic for AI-generated words",
-                    # Remove on_change to prevent automatic generation
-                )
-            
-            with gen_col:
-                # Add custom CSS for the generate button
-                st.markdown(
-                    """
-                    <style>
-                    .st-key-ai_generate_btn {
-                        margin-top: 1.85rem;  /* Align with text input */
-                    }
-                    .st-key-ai_generate_btn button {
-                        aspect-ratio: auto !important;
-                        height: auto !important;
-                        padding: 0.5rem 0.75rem !important;
-                    }
-                    </style>
-                    """,
-                    unsafe_allow_html=True,
-                )
-                st.button(
-                    "🎲",
-                    key="ai_generate_btn",
-                    help="Generate wordlist from topic",
-                    on_click=_on_ai_generate,
-                    use_container_width=True,
-                )
-            
-            # Display wordlist info below topic input
-            info_text = get_wordlist_info(
-                use_ai=True,
-                ai_topic=st.session_state.ai_topic
-            )
-            if info_text:
-                st.caption(info_text)
-        
-        # Add Show Grid ticks option
-        if "show_grid_ticks" not in st.session_state:
-            st.session_state.show_grid_ticks = False
-        st.checkbox("Show Grid ticks", value=st.session_state.show_grid_ticks, key="show_grid_ticks")
-        
-        # Add Spacer option
-        spacer_options = [0,1,2]
-        if "spacer" not in st.session_state:
-            st.session_state.spacer = 1
-        st.selectbox(
-            "Spacer (space between words)",
-            options=spacer_options,
-            index=spacer_options.index(st.session_state.spacer),
-            key="spacer",
-            on_change=_on_game_option_change,  # add callback
-        )
-
-        # Add Show Incorrect Guesses option - now enabled by default
-        if "show_incorrect_guesses" not in st.session_state:
-            st.session_state.show_incorrect_guesses = True
-        st.checkbox("Show incorrect guesses", value=st.session_state.show_incorrect_guesses, key="show_incorrect_guesses")
+def _handle_audio():
+    # Initialize state if needed
+    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 "effects_volume" not in st.session_state:
+        st.session_state.effects_volume = 25
+    if "enable_sound_effects" not in st.session_state:
+        st.session_state.enable_sound_effects = False
 
-        # NEW: Add Show Challenge Share Links option - default ON
-        if "show_challenge_share_links" not in st.session_state:
-            st.session_state.show_challenge_share_links = True
-        st.checkbox("Show Challenge Share Links", value=st.session_state.show_challenge_share_links, key="show_challenge_share_links")
+    tracks = get_audio_tracks()
+    enabled = st.session_state.music_enabled
+    
+    if tracks:
+        options = [p for _, p in tracks]
+        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]
         
-        # NEW: Initialize Enable Free Letters (default OFF)
-        if "enable_free_letters" not in st.session_state:
-            st.session_state.enable_free_letters = False
-        st.checkbox("Enable Free Letters (2 per game)", value=st.session_state.enable_free_letters, key="enable_free_letters")
-
-        # Audio settings
-        st.header("Audio")
-        tracks = get_audio_tracks()
-        st.caption(f"{len(tracks)} audio file{'s' if len(tracks) != 1 else ''} found in wrdler/assets/audio/music")
-
-        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
-        # --- Add sound effects volume ---
-        if "effects_volume" not in st.session_state:
-            st.session_state.effects_volume = 25
-        # --- Add enable sound effects (default OFF) ---
-        if "enable_sound_effects" not in st.session_state:
-            st.session_state.enable_sound_effects = False
-        st.checkbox("Enable Sound Effects", value=st.session_state.enable_sound_effects, key="enable_sound_effects")
-
-        enabled = st.checkbox("Enable music", value=st.session_state.music_enabled, key="music_enabled")
-
-        st.slider(
-            "Volume",
-        0,
-        100,
-         value=int(st.session_state.music_volume),
-         step=1,
-         key="music_volume",
-         disabled=not (enabled and bool(tracks)),
-         )
-
-                # --- Add sound effects volume slider ---
-        st.slider(
-                    "Sound Effects Volume",
-        0,
-        100,
-         value=int(st.session_state.effects_volume),
-         step=1,
-         key="effects_volume",
-         )
-
-        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,
-            )
-            src_url = _load_audio_data_url(selected_path) if enabled else None
-            _mount_background_audio(enabled, src_url, (st.session_state.music_volume or 0) / 100)
-        else:
-            st.caption("Place .mp3 files in wrdler/assets/audio/music to enable music.")
-            _mount_background_audio(False, None, 0.0)
-
-        _inject_audio_control_sync()
-        st.markdown(versions_html(), unsafe_allow_html=True)
-
+        selected_path = st.session_state.music_track_path
+        src_url = _load_audio_data_url(selected_path) if enabled else None
+        _mount_background_audio(enabled, src_url, (st.session_state.music_volume or 0) / 100)
+    else:
+        _mount_background_audio(False, None, 0.0)
 
 # NOTE: Radar/scope visualization functions removed for Wrdler (Sprint 3)
 # - get_scope_image() removed
@@ -1658,6 +1405,16 @@ def _render_guess_form(state: GameState):
           .st-emotion-cache-1xwdq91, .st-emotion-cache-1r70o5 {
               max-width: max-content; min-width:33%;
           }
+          .st-emotion-cache-emqb34 {
+            min-width: calc(50% - 1.5rem);
+            width: calc(50% - 1.5rem);
+            flex:unset;
+          }
+          .st-emotion-cache-1c94k11 {
+            min-width: calc(50% - 1.5rem);
+            width: calc(50% - 1.5rem);
+            flex:unset;
+          }
         }
         </style>
         """,
@@ -2319,10 +2076,6 @@ if _Dialog:
     @_Dialog("Game Over")
     def _game_over_dialog(state: GameState):
         _game_over_content(state)
-
-    @_Dialog("Filter Results")
-    def _filter_results_dialog(count, words, filename):
-        _filter_results_content(count, words, filename)
 else:
     def _game_over_dialog(state: GameState):
         modal_ctx = getattr(st, "modal", None)
@@ -2334,15 +2087,6 @@ else:
             st.subheader("Game Over")
             _game_over_content(state)
 
-    def _filter_results_dialog(count, words, filename):
-        modal_ctx = getattr(st, "modal", None)
-        if callable(modal_ctx):
-            with modal_ctx("Filter Results"):
-                _filter_results_content(count, words, filename)
-        else:
-            st.info(f"Removed {count} words from {filename}")
-            st.text_area("Removed Words", value="\n".join(words), height=200)
-
 def _render_game_over(state: GameState):
     # Use hide_gameover_overlay (same key as run_app) with inverted logic
     visible = not st.session_state.get("hide_gameover_overlay", False) and is_game_over(state)
@@ -2412,44 +2156,16 @@ def _on_game_option_change() -> None:
     # Start a fresh game with updated options
     _new_game()
 
-def _on_wordlist_change() -> None:
-    """
-    Callback when wordlist selection changes.
-    Updates session state flags for AI vs file mode.
-    """
-    selected = st.session_state.get("wordlist_selector")
-    
-    if selected == "AI Generated":
-        st.session_state.use_ai_wordlist = True
-        # Preserve current AI topic or use default
-        if "ai_topic" not in st.session_state:
-            st.session_state.ai_topic = "English"
-        # Don't trigger new game automatically for AI mode
-        # User must click Generate button explicitly
-    else:
-        st.session_state.use_ai_wordlist = False
-        st.session_state.selected_wordlist = selected
-        # Trigger new game immediately for file-based wordlists
-        _on_game_option_change()
-
-
-def _on_ai_generate() -> None:
-    """
-    Callback when Generate button is clicked for AI wordlist.
-    Triggers new game generation with AI words.
-    """
-    # Start a fresh game with AI-generated words
-    _on_game_option_change()
-
 def _render_footer(current_page: str = "play"):
     """Render footer with navigation links to leaderboards and main game.
     
     Args:
-        current_page: Which page is currently active ("play", "today", "daily", "weekly", "history")
+        current_page: Which page is currently active ("play", "today", "daily", "weekly", "history", "settings")
     """
     # Determine which link should be highlighted as active
     play_active = "active" if current_page == "play" else ""
     leaderboard_active = "active" if current_page in {"today", "daily", "weekly", "history"} else ""
+    settings_active = "active" if current_page == "settings" else ""
     
     # Check if we're in challenge mode and need to preserve game_id
     game_id = None
@@ -2467,16 +2183,14 @@ def _render_footer(current_page: str = "play"):
     # Build URLs with game_id if in challenge mode
     if game_id:
         today_url = f"?page=today&game_id={game_id}"
-        daily_url = f"?page=daily&game_id={game_id}"
-        weekly_url = f"?page=weekly&game_id={game_id}"
         leaderboard_url = f"?page=today&game_id={game_id}"
         play_url = f"?game_id={game_id}"
+        settings_url = f"?page=settings&game_id={game_id}"
     else:
         today_url = "?page=today"
-        daily_url = "?page=daily"
-        weekly_url = "?page=weekly"
         leaderboard_url = "?page=today"
         play_url = "/"
+        settings_url = "?page=settings"
     
     st.markdown(
         f"""
@@ -2537,6 +2251,7 @@ def _render_footer(current_page: str = "play"):
             <nav class="bw-footer-nav">
                 <a href="{leaderboard_url}" title="View Leaderboards" target="_self" class="{leaderboard_active}">🏆 Leaderboard</a>
                 <a href="{play_url}" title="Play Wrdler" target="_self" class="{play_active}">🎮 Play</a>
+                <a href="{settings_url}" title="Settings" target="_self" class="{settings_active}">⚙️ Settings</a>
             </nav>
         </div>
         """,
@@ -2562,8 +2277,19 @@ def run_app():
             pass
         st.session_state["hide_gameover_overlay"] = True
 
+    # Handle audio globally
+    _handle_audio()
+
     # Handle page navigation via query params
     page = params.get("page", "")
+    
+    if page == "settings":
+        st.markdown(ocean_background_css, unsafe_allow_html=True)
+        inject_ocean_layers()
+        render_settings_page(_on_game_option_change)
+        _render_footer(current_page="settings")
+        return
+
     if page in {"today", "daily", "weekly"}:
         from .leaderboard_page import render_leaderboard_page
         st.markdown(ocean_background_css, unsafe_allow_html=True)
@@ -2609,7 +2335,6 @@ def run_app():
     st.markdown(ocean_background_css, unsafe_allow_html=True)
     inject_ocean_layers()  # <-- add the animated layers
     _render_header()
-    _render_sidebar()
 
     state = _to_state()