Update to add shiny-border part 1

gradio_app.py

@@ -0,0 +1,25 @@
+"""
+Wrdler - Gradio Application Entry Point
+
+A vocabulary puzzle game with an 8x6 grid and 6 hidden words.
+This is the Gradio version, running alongside the Streamlit app.
+
+Usage:
+    python gradio_app.py
+    # or
+    gradio gradio_app.py
+"""
+
+import gradio as gr
+from wrdler.gradio_ui import create_app
+
+# Create the Gradio app
+demo = create_app()
+
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        share=False,
+        show_error=True
+    )

requirements.txt

@@ -12,4 +12,5 @@ mypy
 requests
 huggingface_hub
 python-dotenv
-google-api-core
+google-api-core
+gradio>=4.0.0

style_wrdler.css

@@ -0,0 +1,651 @@
+/* Wrdler - Custom CSS for Gradio App */
+/* Based on Surn/beeuty theme patterns */
+
+.interface-wrapper {
+    max-width: 1200px;
+    margin: 0 auto;
+}
+
+.centered {
+    margin: 0 auto;
+    display: block;
+    text-align: center;
+}
+
+/* Grid Container - for native Gradio buttons with shiny-border */
+.wrdler-grid-container {
+    position: relative;
+    padding: 4px;
+    background: linear-gradient(-45deg, #a1a1a1, #ffffff, #a1a1a1, #666666);
+    border-radius: 1.25rem;
+    overflow: hidden;
+    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
+    max-width: 520px;
+    margin: 0 auto 16px auto;
+    font-weight: 600;
+}
+
+/* Inner container with original grid colors */
+.wrdler-grid-container > div {
+    background: linear-gradient(145deg, #1a1a2e, #16213e);
+    border-radius: 1rem;
+    padding: 12px;
+}
+
+/* Shiny hover effect for grid */
+.wrdler-grid-container::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;
+    z-index: 1;
+    pointer-events: none;
+}
+
+.wrdler-grid-container:hover::before {
+    left: 100%;
+}
+.prose table, .wrdler-score-panel-container tr.hidden td {
+    border: none;
+    color: #ffffff;
+    font-weight: 600;
+}
+.wrdler-grid-container .shiny-border {
+    position: relative;
+    padding: 12px;
+    background: #333;
+    color: #ffffff !important;
+    border-radius: 1.25rem;
+    overflow: hidden;
+    /*background: linear-gradient(-45deg, #a1a1a1, #ffffff, #a1a1a1, #666666);*/
+    border-width: 12px !important;
+    border-image: linear-gradient(-45deg, #a1a1a1, #fff, #a1a1a1, #666) !important;
+}
+.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%; }
+
+.wrdler-grid-row {
+    gap: 4px 8px !important;
+    justify-content: center !important;
+    flex-wrap: nowrap !important;
+    margin-bottom: 6px !important;
+}
+
+.wrdler-grid-row:last-child {
+    margin-bottom: 0 !important;
+}
+
+.wrdler-grid-row > div {
+    flex: 0 0 auto !important;
+    min-width: 50px !important;
+}
+
+/* Grid cell buttons - unrevealed (clickable) */
+.grid-cell-unrevealed button {
+    min-width: 50px !important;
+    height: 48px !important;
+    font-size: 1.3rem !important;
+    font-weight: 700 !important;
+    border-radius: 6px !important;
+    padding: 0 !important;
+    background: linear-gradient(145deg, #3a7bd5, #00d2ff) !important;
+    border: 2px solid #00d2ff !important;
+    color: #ffffff !important;
+    cursor: pointer !important;
+    box-shadow: 0 2px 8px rgba(0, 210, 255, 0.3) !important;
+    transition: all 0.2s ease !important;
+}
+
+.grid-cell-unrevealed button:hover {
+    background: linear-gradient(145deg, #00d2ff, #3a7bd5) !important;
+    transform: translateY(-2px);
+    box-shadow: 0 4px 12px rgba(0, 210, 255, 0.5) !important;
+}
+
+/* Grid cell buttons - revealed */
+.grid-cell-revealed button {
+    min-width: 50px !important;
+    height: 48px !important;
+    font-size: 1.3rem !important;
+    font-weight: 700 !important;
+    border-radius: 6px !important;
+    padding: 0 !important;
+    background: linear-gradient(145deg, #d4f1f9, #a8e6cf) !important;
+    border: 2px solid #00bfa5 !important;
+    color: #1a1a2e !important;
+    cursor: default !important;
+}
+
+/* Empty revealed cells (middle dot) */
+.grid-cell-revealed button:has(span:empty),
+.grid-cell-revealed button[value="·"] {
+    background: #2d2d44 !important;
+    border: 2px solid #3d3d5c !important;
+    color: #5d5d7c !important;
+}
+
+/* Legacy CSS for HTML grid (kept for compatibility) */
+.wrdler-grid {
+    display: flex;
+    flex-direction: column;
+    gap: 4px 8px;
+    padding: 12px;
+    background: linear-gradient(145deg, #1a1a2e, #16213e);
+    border-radius: 12px;
+    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
+    max-width: 480px;
+    margin: 0 auto;
+    font-weight: 700;
+
+}
+
+.wrdler-row {
+    display: flex;
+    gap: 4px 8px;
+    justify-content: center;
+}
+
+/* Grid Cells (HTML version) */
+.wrdler-cell {
+    width: 56px;
+    height: 52px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 1.4rem;
+    font-weight: 700;
+    border-radius: 6px;
+    transition: all 0.2s ease;
+    user-select: none;
+}
+
+/* Letter buttons row */
+.letter-buttons-row {
+    gap: 4px !important;
+    flex-wrap: wrap !important;
+    justify-content: center !important;
+    margin-bottom: 12px !important;
+}
+
+.letter-buttons-row > div {
+    flex: 0 0 auto !important;
+}
+
+/* Letter button - available */
+.letter-btn-available button {
+    min-width: 36px !important;
+    height: 36px !important;
+    font-size: 1rem !important;
+    font-weight: 700 !important;
+    border-radius: 50% !important;
+    padding: 0 !important;
+    background: linear-gradient(145deg, #00bfa5, #00d2ff) !important;
+    border: 2px solid #00bfa5 !important;
+    color: #ffffff !important;
+    cursor: pointer !important;
+    box-shadow: 0 2px 8px rgba(0, 191, 165, 0.3) !important;
+    transition: all 0.2s ease !important;
+}
+
+.letter-btn-available button:hover {
+    background: linear-gradient(145deg, #00d2ff, #00bfa5) !important;
+    transform: translateY(-2px) scale(1.1);
+    box-shadow: 0 4px 12px rgba(0, 191, 165, 0.5) !important;
+}
+
+/* Letter button - used */
+.letter-btn-used button {
+    min-width: 36px !important;
+    height: 36px !important;
+    font-size: 1rem !important;
+    font-weight: 700 !important;
+    border-radius: 50% !important;
+    padding: 0 !important;
+    background: #3d3d5c !important;
+    border: 2px solid #5d5d7c !important;
+    color: #7d7d9c !important;
+    cursor: not-allowed !important;
+    opacity: 0.7 !important;
+}
+
+/* Free Letter Selection (legacy) */
+.wrdler-free-letters {
+    background: linear-gradient(145deg, rgba(26, 26, 46, 0.9), rgba(22, 33, 62, 0.9));
+    border-radius: 12px;
+    padding: 16px;
+    margin-bottom: 16px;
+    border: 2px solid rgba(0, 210, 255, 0.3);
+    font-weight:bolder;
+}
+
+.free-letter-header {
+    text-align: center;
+    font-size: 1.1rem;
+    font-weight: 600;
+    color: #00d2ff;
+    margin-bottom: 12px;
+}
+
+.free-letter-buttons {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+    justify-content: center;
+}
+
+.wrdler-free-btn {
+    width: 40px;
+    height: 40px;
+    border-radius: 50%;
+    border: 2px solid #00bfa5;
+    background: linear-gradient(145deg, #00bfa5, #00d2ff);
+    color: #ffffff;
+    font-weight: 700;
+    font-size: 1rem;
+    cursor: pointer;
+    transition: all 0.2s ease;
+    box-shadow: 0 2px 8px rgba(0, 191, 165, 0.3);
+}
+
+.wrdler-free-btn:hover {
+    background: linear-gradient(145deg, #00d2ff, #00bfa5);
+    transform: translateY(-2px) scale(1.1);
+    box-shadow: 0 4px 12px rgba(0, 191, 165, 0.5);
+}
+
+.wrdler-free-btn.used {
+    background: #3d3d5c;
+    border-color: #5d5d7c;
+    color: #7d7d9c;
+    cursor: not-allowed;
+    opacity: 0.6;
+}
+
+.wrdler-free-letters-done {
+    text-align: center;
+    padding: 12px;
+    background: rgba(0, 191, 165, 0.2);
+    border-radius: 8px;
+    color: #00bfa5;
+    font-weight: 600;
+    margin-bottom: 16px;
+}
+
+/* Score Panel */
+.wrdler-score-panel {
+    background: linear-gradient(145deg, #1a1a2e, #16213e);
+    border-radius: 12px;
+    padding: 16px;
+    border: 2px solid rgba(0, 210, 255, 0.3);
+}
+
+.score-header {
+    text-align: center;
+    font-size: 1.5rem;
+    font-weight: 700;
+    color: #ffffff;
+    margin-bottom: 12px;
+}
+
+.score-value {
+    color: #00d2ff;
+    font-size: 2rem;
+}
+
+.timer {
+    text-align: center;
+    font-size: 1.1rem;
+    color: #a8e6cf;
+    margin-bottom: 16px;
+}
+
+.time-value {
+    font-family: monospace;
+    font-weight: 700;
+}
+
+.words-table {
+    margin-top: 16px;
+}
+
+.words-table table {
+    width: 100%;
+    border-collapse: collapse;
+}
+
+.words-table th,
+.words-table td {
+    padding: 8px 12px;
+    text-align: center;
+    border-bottom: 1px solid rgba(0, 210, 255, 0.2);
+}
+
+.words-table th {
+    color: #00d2ff;
+    font-weight: 600;
+}
+
+.words-table tr.found td {
+    color: #00bfa5;
+    font-weight: 600;
+}
+
+.words-table tr.hidden td {
+    color: #7d7d9c;
+    font-family: monospace;
+}
+
+/* Game Over Display */
+.wrdler-game-over {
+    background: linear-gradient(145deg, rgba(0, 191, 165, 0.1), rgba(0, 210, 255, 0.1));
+    border: 2px solid #00bfa5;
+    border-radius: 12px;
+    padding: 24px;
+    margin-top: 16px;
+    text-align: center;
+}
+
+.wrdler-game-over h2 {
+    color: #00d2ff;
+    font-size: 1.8rem;
+    margin-bottom: 16px;
+}
+
+.final-score {
+    font-size: 2rem;
+    font-weight: 700;
+    color: #00bfa5;
+    margin-bottom: 8px;
+}
+
+.tier {
+    font-size: 1.3rem;
+    color: #ffd700;
+    font-weight: 600;
+    margin-bottom: 8px;
+}
+
+.final-time {
+    font-size: 1.1rem;
+    color: #a8e6cf;
+    margin-bottom: 16px;
+}
+
+.breakdown {
+    margin-top: 16px;
+}
+
+.breakdown h3 {
+    color: #00d2ff;
+    margin-bottom: 12px;
+}
+
+.breakdown table {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 0 auto;
+    max-width: 400px;
+}
+
+.breakdown th,
+.breakdown td {
+    padding: 6px 10px;
+    text-align: center;
+    border-bottom: 1px solid rgba(0, 210, 255, 0.2);
+}
+
+.breakdown th {
+    color: #00d2ff;
+    font-size: 0.9rem;
+}
+
+.breakdown td {
+    color: #a8e6cf;
+}
+
+/* Guess Input Styling */
+#guess-input {
+    font-size: 1.2rem;
+}
+
+#guess-btn {
+    min-width: 100px;
+}
+
+/* Status Message */
+.status-msg {
+    text-align: center;
+    padding: 12px;
+    background: rgba(0, 210, 255, 0.1);
+    border-radius: 8px;
+    margin-top: 12px;
+}
+
+/* Responsive Design */
+@media (max-width: 768px) {
+    .wrdler-grid {
+        max-width: 100%;
+        padding: 8px;
+    }
+
+    .wrdler-cell {
+        width: 42px;
+        height: 38px;
+        font-size: 1.1rem;
+    }
+
+    .wrdler-free-btn {
+        width: 32px;
+        height: 32px;
+        font-size: 0.9rem;
+    }
+
+    .score-header {
+        font-size: 1.2rem;
+    }
+
+    .score-value {
+        font-size: 1.5rem;
+    }
+}
+
+@media (max-width: 480px) {
+    .wrdler-cell {
+        width: 36px;
+        height: 32px;
+        font-size: 1rem;
+    }
+
+    .wrdler-row {
+        gap: 2px;
+    }
+
+    .wrdler-grid {
+        gap: 2px;
+    }
+}
+
+/* Dark mode adjustments (Beeuty theme compatibility) */
+.dark .wrdler-grid {
+    background: linear-gradient(145deg, #0d0d1a, #1a1a2e);
+}
+
+.dark .wrdler-score-panel {
+    background: linear-gradient(145deg, #0d0d1a, #1a1a2e);
+}
+
+/* Toast notifications */
+.toast-body.info {
+    background-color: rgba(0, 210, 255, 0.75);
+}
+
+.dark .toast-body.info {
+    background-color: rgba(0, 191, 165, 0.75);
+}
+
+/* Accordion styling */
+.accordion {
+    border-radius: 8px;
+}
+
+/* Hide bridge elements - keep functional but visually hidden */
+/* Using clip-rect to hide visually while maintaining DOM accessibility */
+.hidden-bridge {
+    position: absolute !important;
+    width: 1px !important;
+    height: 1px !important;
+    padding: 0 !important;
+    margin: -1px !important;
+    overflow: hidden !important;
+    clip: rect(0, 0, 0, 0) !important;
+    white-space: nowrap !important;
+    border: 0 !important;
+    /* Keep opacity at 1 and pointer-events enabled for JS interaction */
+    opacity: 1 !important;
+    pointer-events: auto !important;
+}
+
+/* Ensure the actual input/button inside bridge can receive events */
+.hidden-bridge input,
+.hidden-bridge textarea,
+.hidden-bridge button {
+    pointer-events: auto !important;
+}
+
+/* Challenge Mode Leaderboard */
+.wrdler-challenge-banner {
+    background: linear-gradient(145deg, rgba(0, 191, 165, 0.15), rgba(0, 210, 255, 0.15));
+    border: 2px solid #00bfa5;
+    border-radius: 12px;
+    padding: 16px;
+    margin-bottom: 16px;
+    text-align: center;
+}
+
+.wrdler-challenge-banner h3 {
+    color: #00d2ff;
+    margin: 0 0 8px 0;
+    font-size: 1.3rem;
+}
+
+.challenge-id {
+    color: #a8e6cf;
+    font-family: monospace;
+    font-size: 0.9rem;
+    margin-bottom: 12px;
+}
+
+.wrdler-challenge-banner .leaderboard table {
+    width: 100%;
+    max-width: 400px;
+    margin: 0 auto;
+    border-collapse: collapse;
+}
+
+.wrdler-challenge-banner .leaderboard th,
+.wrdler-challenge-banner .leaderboard td {
+    padding: 6px 10px;
+    text-align: center;
+    border-bottom: 1px solid rgba(0, 210, 255, 0.2);
+}
+
+.wrdler-challenge-banner .leaderboard th {
+    color: #00d2ff;
+    font-size: 0.85rem;
+}
+
+.wrdler-challenge-banner .leaderboard td {
+    color: #ffffff;
+}
+
+/* Share Challenge Section */
+.share-challenge {
+    margin-top: 16px;
+    padding: 12px;
+    background: rgba(0, 191, 165, 0.1);
+    border-radius: 8px;
+}
+
+.share-challenge input {
+    width: 100%;
+    padding: 8px;
+    border: 1px solid #00bfa5;
+    border-radius: 4px;
+    background: rgba(26, 26, 46, 0.9);
+    color: #ffffff;
+    font-family: monospace;
+}
+
+.share-challenge-btn {
+    margin-top: 8px;
+    padding: 8px 16px;
+    background: linear-gradient(145deg, #00bfa5, #00d2ff);
+    border: none;
+    border-radius: 6px;
+    color: #ffffff;
+    font-weight: 600;
+    cursor: pointer;
+}
+
+.share-challenge-btn:hover {
+    background: linear-gradient(145deg, #00d2ff, #00bfa5);
+}
+
+/* Tab Styling */
+.tabs {
+    background: transparent !important;
+}
+
+.tab-nav {
+    background: linear-gradient(145deg, #1a1a2e, #16213e) !important;
+    border-radius: 12px 12px 0 0 !important;
+    padding: 8px 8px 0 8px !important;
+    border: none !important;
+}
+
+.tab-nav button {
+    background: transparent !important;
+    color: #a8e6cf !important;
+    border: none !important;
+    padding: 12px 24px !important;
+    font-weight: 600 !important;
+    border-radius: 8px 8px 0 0 !important;
+    transition: all 0.2s ease !important;
+}
+
+.tab-nav button:hover {
+    background: rgba(0, 210, 255, 0.1) !important;
+    color: #00d2ff !important;
+}
+
+.tab-nav button.selected {
+    background: linear-gradient(145deg, #00bfa5, #00d2ff) !important;
+    color: #ffffff !important;
+}
+
+.tabitem {
+    background: linear-gradient(145deg, rgba(26, 26, 46, 0.5), rgba(22, 33, 62, 0.5)) !important;
+    border-radius: 0 0 12px 12px !important;
+    padding: 16px !important;
+}
+
+/* Settings Tab Specific */
+.settings-section h3,
+.tabitem h3 {
+    color: #00d2ff !important;
+    margin-bottom: 16px !important;
+    font-size: 1.2rem !important;
+}
+
+.tabitem .gr-button-lg {
+    min-width: 200px !important;
+    margin-top: 16px !important;
+}

wrdler/assets/audio/effects/congratulations.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:232ca809d3940e7d3491f29ac97230fe0691f21e46993d6d3f42f905c9d225bf
+size 1811619

wrdler/gradio_ui.py

@@ -0,0 +1,1154 @@
+"""
+Wrdler - Gradio UI Module
+
+Main Gradio interface for the Wrdler vocabulary puzzle game.
+Implements the same gameplay as the Streamlit version with Gradio components.
+"""
+
+from __future__ import annotations
+
+import os
+import json
+import copy
+from datetime import datetime
+from typing import Dict, List, Optional, Set, Tuple, Any
+from functools import lru_cache, partial
+import base64
+import mimetypes
+
+import gradio as gr
+
+from .models import Coord, Word, Puzzle, GameState
+from .logic import (
+    build_letter_map,
+    reveal_cell,
+    reveal_free_letter,
+    guess_word,
+    is_game_over,
+    auto_mark_completed_words,
+    compute_tier,
+)
+from .generator import generate_puzzle
+
+# Version info
+from . import __version__
+
+# Constants
+GRID_ROWS = 6
+GRID_COLS = 8
+MAX_FREE_LETTERS = 2
+
+
+# ---------------------------------------------------------------------------
+# Word Loading (Gradio-compatible, no Streamlit dependencies)
+# ---------------------------------------------------------------------------
+
+FALLBACK_WORDS: Dict[int, List[str]] = {
+    4: ["TREE", "BOAT", "WIND", "FROG", "LION", "MOON", "FORK", "GLOW", "GAME", "CODE",
+        "DATA", "BLUE", "GOLD", "ROAD", "STAR", "FISH", "BIRD", "RAIN", "SNOW", "LEAF",
+        "ROCK", "WAVE", "FIRE", "SAND", "LAKE"],
+    5: ["APPLE", "RIVER", "STONE", "PLANT", "MOUSE", "BOARD", "CHAIR", "SCALE", "SMILE",
+        "CLOUD", "DRONE", "LEVEL", "ZEBRA", "BRAVE", "CROWN", "GRAPE", "LEMON", "PEARL",
+        "STORM", "TIGER", "WHALE", "BEACH", "DREAM", "FLAME", "OCEAN"],
+    6: ["ORANGE", "PYTHON", "STREAM", "MARKET", "FOREST", "THRIVE", "LOGGER", "BREATH",
+        "DOMAIN", "GALAXY", "BUTTON", "JUNGLE", "PLANET", "PUZZLE", "QUARTZ", "ROCKET",
+        "SALMON", "TEMPLE", "VALLEY", "WINTER", "BRANCH", "CASTLE", "FLOWER", "ISLAND",
+        "SUNSET"],
+}
+
+MIN_REQUIRED = 25
+
+
+# ---------------------------------------------------------------------------
+# Audio Utilities (Gradio-compatible)
+# ---------------------------------------------------------------------------
+
+def _get_music_dir() -> str:
+    return os.path.join(os.path.dirname(__file__), "assets", "audio", "music")
+
+
+def _get_effects_dir() -> str:
+    return os.path.join(os.path.dirname(__file__), "assets", "audio", "effects")
+
+
+def get_audio_tracks() -> List[Tuple[str, str]]:
+    """Return list of (label, path) for music files."""
+    audio_dir = _get_music_dir()
+    if not os.path.isdir(audio_dir):
+        return []
+    tracks = []
+    for fname in os.listdir(audio_dir):
+        if fname.lower().endswith('.mp3'):
+            path = os.path.join(audio_dir, fname)
+            name = os.path.splitext(fname)[0]
+            tracks.append((name, path))
+    return sorted(tracks)
+
+
+def get_sound_effect_files() -> Dict[str, str]:
+    """Return dict of effect_name -> path."""
+    audio_dir = _get_effects_dir()
+    if not os.path.isdir(audio_dir):
+        return {}
+
+    effect_names = ["correct_guess", "incorrect_guess", "hit", "miss", "congratulations"]
+    result = {}
+    for name in effect_names:
+        for ext in (".mp3", ".wav"):
+            path = os.path.join(audio_dir, f"{name}{ext}")
+            if os.path.exists(path):
+                result[name] = path
+                break
+    return result
+
+
+@lru_cache(maxsize=32)
+def load_audio_data_url(path: str) -> str:
+    """Convert audio file to data URL for browser playback."""
+    mime, _ = mimetypes.guess_type(path)
+    if not mime:
+        mime = "audio/mpeg"
+    try:
+        with open(path, "rb") as fp:
+            encoded = base64.b64encode(fp.read()).decode("ascii")
+        return f"data:{mime};base64,{encoded}"
+    except Exception:
+        return ""
+
+
+def render_audio_player_html(
+    effect_name: Optional[str] = None,
+    volume: float = 0.5,
+    enabled: bool = True
+) -> str:
+    """Generate HTML to play a sound effect."""
+    if not enabled or not effect_name:
+        return ""
+
+    sound_files = get_sound_effect_files()
+    if effect_name not in sound_files:
+        return ""
+
+    data_url = load_audio_data_url(sound_files[effect_name])
+    if not data_url:
+        return ""
+
+    vol = max(0.0, min(1.0, float(volume)))
+
+    return f'''
+<script>
+(function(){{
+    const audio = new Audio("{data_url}");
+    audio.volume = {vol:.3f};
+    audio.play().catch(e => console.log('Audio play blocked'));
+}})();
+</script>
+'''
+
+
+# ---------------------------------------------------------------------------
+# Word Loading (Gradio-compatible, no Streamlit dependencies)
+# ---------------------------------------------------------------------------
+
+def get_wordlist_files() -> List[str]:
+    """Get available word list files."""
+    words_dir = os.path.join(os.path.dirname(__file__), "words")
+    if not os.path.isdir(words_dir):
+        return []
+    files = [f for f in os.listdir(words_dir) if f.lower().endswith(".txt")]
+    return sorted(files)
+
+
+@lru_cache(maxsize=32)
+def load_word_list_gradio(selected_file: Optional[str] = None) -> Dict[int, List[str]]:
+    """Load word list without Streamlit dependencies."""
+    import re
+
+    words_by_len: Dict[int, List[str]] = {4: [], 5: [], 6: []}
+
+    try:
+        words_dir = os.path.join(os.path.dirname(__file__), "words")
+
+        if selected_file:
+            path = os.path.join(words_dir, selected_file)
+        else:
+            path = os.path.join(words_dir, "wordlist.txt")
+
+        with open(path, "r", encoding="utf-8") as f:
+            text = f.read()
+
+        seen = {4: set(), 5: set(), 6: set()}
+        for raw in text.splitlines():
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            if "#" in line:
+                line = line.split("#", 1)[0].strip()
+            word = line.upper()
+            if not re.fullmatch(r"[A-Z]+", word):
+                continue
+            L = len(word)
+            if L in (4, 5, 6) and word not in seen[L]:
+                words_by_len[L].append(word)
+                seen[L].add(word)
+
+        # Check minimum requirements
+        counts = {k: len(v) for k, v in words_by_len.items()}
+        if all(counts[k] >= MIN_REQUIRED for k in (4, 5, 6)):
+            return words_by_len
+
+        # Fallback for insufficient words
+        return {
+            4: words_by_len[4] if counts[4] >= MIN_REQUIRED else FALLBACK_WORDS[4],
+            5: words_by_len[5] if counts[5] >= MIN_REQUIRED else FALLBACK_WORDS[5],
+            6: words_by_len[6] if counts[6] >= MIN_REQUIRED else FALLBACK_WORDS[6],
+        }
+
+    except Exception:
+        return FALLBACK_WORDS.copy()
+
+
+# ---------------------------------------------------------------------------
+# Game State Management
+# ---------------------------------------------------------------------------
+
+def create_new_game_state(
+    wordlist: str = "classic.txt",
+    game_mode: str = "classic",
+    seed: Optional[int] = None
+) -> Dict[str, Any]:
+    """Create a new game state dictionary for gr.State."""
+    words_by_len = load_word_list_gradio(wordlist)
+    puzzle = generate_puzzle(
+        grid_rows=GRID_ROWS,
+        grid_cols=GRID_COLS,
+        words_by_len=words_by_len,
+        seed=seed
+    )
+    letter_map = build_letter_map(puzzle)
+
+    # Convert Coord keys to string for JSON serialization
+    letter_map_serializable = {f"{c.x},{c.y}": v for c, v in letter_map.items()}
+
+    # Get unique letters in the puzzle (sorted for consistent button order)
+    puzzle_letters = sorted(set(letter for word in puzzle.words for letter in word.text.upper()))
+
+    return {
+        "puzzle_uid": puzzle.uid,
+        "puzzle_words": [(w.text, w.start.x, w.start.y, w.direction) for w in puzzle.words],
+        "puzzle_letters": puzzle_letters,  # Letters available for free letter selection
+        "grid_rows": GRID_ROWS,
+        "grid_cols": GRID_COLS,
+        "revealed": [],  # List of "x,y" strings
+        "guessed": [],  # List of guessed words
+        "score": 0,
+        "last_action": "Welcome! Choose your 2 free letters to start.",
+        "can_guess": False,
+        "game_mode": game_mode,
+        "points_by_word": {},
+        "start_time": datetime.now().isoformat(),
+        "end_time": None,
+        "free_letters": [],
+        "free_letters_used": 0,
+        "letter_map": letter_map_serializable,
+        "wordlist": wordlist,
+        "incorrect_guesses": [],
+        "game_over": False,
+        # Audio settings
+        "sound_effects_enabled": True,
+        "sound_effects_volume": 50,
+        "music_enabled": False,
+        "music_volume": 30,
+        "pending_sound": None,  # Sound effect to play on next render
+        # Challenge mode
+        "challenge_mode": False,
+        "challenge_sid": None,
+        "challenge_settings": None,
+        "challenge_leaderboard": [],
+    }
+
+
+def state_to_gamestate(state: Dict[str, Any]) -> Tuple[GameState, Dict[Coord, str]]:
+    """Convert state dict to GameState object and letter_map."""
+    # Reconstruct puzzle
+    words = []
+    for text, x, y, direction in state["puzzle_words"]:
+        words.append(Word(text=text, start=Coord(x, y), direction=direction))
+
+    puzzle = Puzzle(
+        words=words,
+        uid=state["puzzle_uid"],
+        grid_rows=state["grid_rows"],
+        grid_cols=state["grid_cols"]
+    )
+
+    # Reconstruct letter map
+    letter_map = {}
+    for coord_str, letter in state["letter_map"].items():
+        x, y = map(int, coord_str.split(","))
+        letter_map[Coord(x, y)] = letter
+
+    # Reconstruct revealed set
+    revealed = set()
+    for coord_str in state["revealed"]:
+        x, y = map(int, coord_str.split(","))
+        revealed.add(Coord(x, y))
+
+    # Parse times
+    start_time = datetime.fromisoformat(state["start_time"]) if state["start_time"] else None
+    end_time = datetime.fromisoformat(state["end_time"]) if state["end_time"] else None
+
+    game_state = GameState(
+        grid_rows=state["grid_rows"],
+        grid_cols=state["grid_cols"],
+        puzzle=puzzle,
+        revealed=revealed,
+        guessed=set(state["guessed"]),
+        score=state["score"],
+        last_action=state["last_action"],
+        can_guess=state["can_guess"],
+        game_mode=state["game_mode"],
+        points_by_word=state["points_by_word"].copy(),
+        start_time=start_time,
+        end_time=end_time,
+        free_letters=set(state["free_letters"]),
+        free_letters_used=state["free_letters_used"]
+    )
+
+    return game_state, letter_map
+
+
+def gamestate_to_dict(gs: GameState, state: Dict[str, Any]) -> Dict[str, Any]:
+    """Update state dict from GameState object."""
+    state["revealed"] = [f"{c.x},{c.y}" for c in gs.revealed]
+    state["guessed"] = list(gs.guessed)
+    state["score"] = gs.score
+    state["last_action"] = gs.last_action
+    state["can_guess"] = gs.can_guess
+    state["points_by_word"] = gs.points_by_word.copy()
+    state["free_letters"] = list(gs.free_letters)
+    state["free_letters_used"] = gs.free_letters_used
+    state["game_over"] = is_game_over(gs)
+    if state["game_over"] and gs.end_time is None:
+        state["end_time"] = datetime.now().isoformat()
+    return state
+
+
+# ---------------------------------------------------------------------------
+# Grid Button Labels
+# ---------------------------------------------------------------------------
+
+def get_cell_label(state: Dict[str, Any], row: int, col: int) -> str:
+    """Get the display label for a grid cell button."""
+    coord_str = f"{row},{col}"
+    revealed_set = set(state.get("revealed", []))
+    letter_map = state.get("letter_map", {})
+
+    if coord_str in revealed_set:
+        letter = letter_map.get(coord_str, "")
+        return letter if letter else "·"  # Middle dot for empty revealed cells
+    else:
+        return "?"
+
+
+def get_cell_variant(state: Dict[str, Any], row: int, col: int) -> str:
+    """Get the button variant for a grid cell."""
+    coord_str = f"{row},{col}"
+    revealed_set = set(state.get("revealed", []))
+    guessed_words = set(state.get("guessed", []))
+    letter_map = state.get("letter_map", {})
+
+    # Check if cell is part of a completed word
+    completed_cells = set()
+    for text, x, y, direction in state.get("puzzle_words", []):
+        if text in guessed_words:
+            for i in range(len(text)):
+                if direction == "H":
+                    completed_cells.add(f"{x},{y+i}")
+                else:
+                    completed_cells.add(f"{x+i},{y}")
+
+    if coord_str in revealed_set:
+        if coord_str in completed_cells:
+            return "secondary"  # Completed word
+        elif letter_map.get(coord_str, ""):
+            return "secondary"  # Revealed letter
+        else:
+            return "secondary"  # Empty cell
+    else:
+        return "primary"  # Unrevealed - clickable
+
+
+def get_all_button_updates(state: Dict[str, Any]) -> List[gr.Button]:
+    """Generate button updates for all 48 grid cells."""
+    updates = []
+    for row in range(GRID_ROWS):
+        for col in range(GRID_COLS):
+            coord_str = f"{row},{col}"
+            revealed_set = set(state.get("revealed", []))
+            is_revealed = coord_str in revealed_set
+
+            label = get_cell_label(state, row, col)
+            variant = get_cell_variant(state, row, col)
+
+            updates.append(gr.Button(
+                value=label,
+                variant=variant,
+                interactive=not is_revealed,
+                elem_classes=["grid-cell-revealed"] if is_revealed else ["grid-cell-unrevealed"]
+            ))
+    return updates
+
+
+def get_puzzle_letters(state: Dict[str, Any]) -> Set[str]:
+    """Get set of unique letters that exist in the puzzle words."""
+    letters = set()
+    for text, x, y, direction in state.get("puzzle_words", []):
+        letters.update(text.upper())
+    return letters
+
+
+def get_available_letters(state: Dict[str, Any]) -> List[str]:
+    """Get list of available letters for free letter selection (only letters in puzzle)."""
+    used_letters = set(state.get("free_letters", []))
+    letters_used = state.get("free_letters_used", 0)
+
+    if letters_used >= MAX_FREE_LETTERS:
+        return []
+
+    # Only show letters that exist in the puzzle and haven't been used
+    puzzle_letters = get_puzzle_letters(state)
+    return sorted([letter for letter in puzzle_letters if letter not in used_letters])
+
+
+def get_all_letter_button_updates(state: Dict[str, Any], all_puzzle_letters: List[str]) -> List[gr.Button]:
+    """Generate button updates for all letter buttons."""
+    used_letters = set(state.get("free_letters", []))
+    letters_used = state.get("free_letters_used", 0)
+    available = letters_used < MAX_FREE_LETTERS
+
+    updates = []
+    for letter in all_puzzle_letters:
+        is_used = letter in used_letters
+        updates.append(gr.Button(
+            value=letter,
+            variant="secondary" if is_used else "primary",
+            interactive=available and not is_used,
+            elem_classes=["letter-btn-used"] if is_used else ["letter-btn-available"]
+        ))
+    return updates
+
+
+def render_free_letters_status(state: Dict[str, Any]) -> str:
+    """Generate status message for free letter selection."""
+    letters_used = state.get("free_letters_used", 0)
+
+    if letters_used >= MAX_FREE_LETTERS:
+        return "Free letters used! Click grid cells to reveal more."
+
+    remaining = MAX_FREE_LETTERS - letters_used
+    return f"Choose {remaining} free letter{'s' if remaining > 1 else ''}:"
+
+
+def render_score_panel_html(state: Dict[str, Any]) -> str:
+    """Generate HTML for the score panel with shiny-border styling."""
+    score = state["score"]
+    guessed = set(state["guessed"])
+    points_by_word = state["points_by_word"]
+    start_time = state["start_time"]
+    end_time = state["end_time"]
+    game_over = state["game_over"]
+
+    # Calculate elapsed time
+    if end_time:
+        start = datetime.fromisoformat(start_time)
+        end = datetime.fromisoformat(end_time)
+        elapsed = (end - start).total_seconds()
+    else:
+        elapsed = 0  # Will be updated by JS
+
+    minutes = int(elapsed // 60)
+    seconds = int(elapsed % 60)
+    time_str = f"{minutes:02d}:{seconds:02d}"
+
+    # Build table rows
+    table_rows = []
+    table_rows.append('<tr><th>Word</th><th>Len</th><th>Bonus</th></tr>')
+
+    for text, x, y, direction in state["puzzle_words"]:
+        if text in guessed:
+            total_points = points_by_word.get(text, len(text))
+            base_points = len(text)
+            bonus_points = total_points - base_points
+            table_rows.append(
+                f'<tr class="found">'
+                f'<td>{text}</td>'
+                f'<td>{base_points}</td>'
+                f'<td>+{bonus_points}</td>'
+                f'</tr>'
+            )
+        else:
+            hidden = "?" * len(text)
+            base_points = len(text)
+            table_rows.append(
+                f'<tr class="hidden">'
+                f'<td>{hidden}</td>'
+                f'<td>{base_points}</td>'
+                f'<td>-</td>'
+                f'</tr>'
+            )
+
+    table_inner = "\n".join(table_rows)
+
+    # Timer HTML
+    if not game_over:
+        timer_html = f'''
+<div class="timer" id="wrdler-timer" data-start="{start_time}">
+    Time: <span class="time-value">{time_str}</span>
+</div>
+<script>
+(function() {{
+    const timerEl = document.getElementById('wrdler-timer');
+    if (!timerEl) return;
+    const startTime = new Date(timerEl.dataset.start);
+    function updateTimer() {{
+        const now = new Date();
+        const elapsed = Math.floor((now - startTime) / 1000);
+        const mins = Math.floor(elapsed / 60);
+        const secs = elapsed % 60;
+        const timeSpan = timerEl.querySelector('.time-value');
+        if (timeSpan) {{
+            timeSpan.textContent = String(mins).padStart(2, '0') + ':' + String(secs).padStart(2, '0');
+        }}
+    }}
+    setInterval(updateTimer, 1000);
+    updateTimer();
+}})();
+</script>
+'''
+    else:
+        timer_html = f'<div class="timer">Time: <span class="time-value">{time_str}</span></div>'
+
+    html = f'''
+    <div class='wrdler-score-panel-container'>
+      <style>
+        .bold-text {{ font-weight: 700; }}
+        .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; color: white; border-radius: 1.25rem; overflow: hidden; background: linear-gradient(-45deg, #a1a1a1, #ffffff, #a1a1a1, #666666); transition: left 0.5s;}}
+        .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; }}
+        .wrdler-score-panel-container {{ height: 100%; overflow: hidden; text-align:center;}}
+        .wrdler-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%; }}
+        .wrdler-score-panel-container {{ height: 100%; overflow: hidden; text-align:center;}}
+        .wrdler-score-panel-container table {{ width: 100%; margin: 0 auto; border-collapse: separate; border-spacing: 0; }}
+        .wrdler-score-panel-container th, .wrdler-score-panel-container td {{ padding: 6px 8px; }}
+        .wrdler-score-panel-container .score-header {{ font-size: 1.5rem; font-weight: 700; color: #1a1a2e; margin-bottom: 8px; }}
+        .wrdler-score-panel-container .score-value {{ color: #00bfa5; font-size: 2rem; }}
+        .wrdler-score-panel-container .timer {{ font-size: 1.1rem; color: #1a1a2e; margin-bottom: 12px; }}
+        .wrdler-score-panel-container .time-value {{ font-family: monospace; font-weight: 700; }}
+        .wrdler-score-panel-container th {{ color: #1a1a2e; font-weight: 600; border-bottom: 2px solid rgba(0, 0, 0, 0.2); background: #000;}}
+        .wrdler-score-panel-container tr {{ border-bottom: 1px solid rgba(0, 0, 0, 0.1); background: #000;}}
+        .wrdler-score-panel-container tr.found td {{ font-weight: 600; background: #000;}}
+        .wrdler-score-panel-container tr.hidden td {{ color: #333; }}
+      </style>
+      <div class="score-header">Score: <span class="score-value">{score}</span></div>
+      {timer_html}      
+      <table class='shiny-border' style=\"border-radius:0.75rem; overflow:hidden; width:100%; margin:0 auto; border-collapse:separate; border-spacing: 0;\">
+        {table_inner}
+      </table>
+    </div>
+    '''
+
+    return html
+
+
+def render_pending_audio_html(state: Dict[str, Any]) -> str:
+    """Render audio HTML for any pending sound effect."""
+    pending = state.get("pending_sound")
+    if not pending:
+        return ""
+
+    enabled = state.get("sound_effects_enabled", True)
+    volume = state.get("sound_effects_volume", 50) / 100.0
+
+    # Clear pending sound
+    state["pending_sound"] = None
+
+    return render_audio_player_html(pending, volume, enabled)
+
+
+def render_challenge_leaderboard_html(state: Dict[str, Any]) -> str:
+    """Generate HTML for challenge mode leaderboard."""
+    if not state.get("challenge_mode") or not state.get("challenge_leaderboard"):
+        return ""
+
+    leaderboard = state["challenge_leaderboard"]
+    sid = state.get("challenge_sid", "")
+
+    html = [
+        '<div class="wrdler-challenge-banner">',
+        '<h3>Challenge Mode</h3>',
+        f'<div class="challenge-id">Challenge: {sid}</div>',
+        '<div class="leaderboard">',
+        '<table>',
+        '<tr><th>#</th><th>Player</th><th>Score</th><th>Time</th></tr>'
+    ]
+
+    # Sort by score desc, then time asc
+    sorted_lb = sorted(leaderboard, key=lambda x: (-x.get("score", 0), x.get("time", 9999)))
+
+    medals = ["🥇", "🥈", "🥉"]
+    for i, entry in enumerate(sorted_lb[:5]):  # Top 5
+        medal = medals[i] if i < 3 else str(i + 1)
+        name = entry.get("username", "Anonymous")
+        score = entry.get("score", 0)
+        time_sec = entry.get("time", 0)
+        mins = time_sec // 60
+        secs = time_sec % 60
+        time_str = f"{mins}:{secs:02d}"
+        html.append(f'<tr><td>{medal}</td><td>{name}</td><td>{score}</td><td>{time_str}</td></tr>')
+
+    html.append('</table></div></div>')
+    return "\n".join(html)
+
+
+def render_game_over_html(state: Dict[str, Any]) -> str:
+    """Generate HTML for game over display."""
+    if not state["game_over"]:
+        return ""
+
+    score = state["score"]
+    tier = compute_tier(score)
+    points_by_word = state["points_by_word"]
+    start_time = state["start_time"]
+    end_time = state["end_time"]
+
+    # Calculate final time
+    if end_time and start_time:
+        start = datetime.fromisoformat(start_time)
+        end = datetime.fromisoformat(end_time)
+        elapsed = (end - start).total_seconds()
+        minutes = int(elapsed // 60)
+        seconds = int(elapsed % 60)
+        time_str = f"{minutes:02d}:{seconds:02d}"
+    else:
+        time_str = "--:--"
+
+    html = [
+        '<div class="wrdler-game-over">',
+        '<h2>Game Over!</h2>',
+        f'<div class="final-score">Score: {score}</div>',
+        f'<div class="tier">{tier}</div>',
+        f'<div class="final-time">Time: {time_str}</div>',
+        '<div class="breakdown"><h3>Score Breakdown</h3><table>',
+        '<tr><th>Word</th><th>Length</th><th>Bonus</th><th>Total</th></tr>'
+    ]
+
+    for text, x, y, direction in state["puzzle_words"]:
+        points = points_by_word.get(text, len(text))
+        base = len(text)
+        bonus = points - base
+        html.append(f'<tr><td>{text}</td><td>{base}</td><td>+{bonus}</td><td>{points}</td></tr>')
+
+    html.append('</table></div>')
+    html.append('</div>')
+
+    return "\n".join(html)
+
+
+# ---------------------------------------------------------------------------
+# Event Handlers
+# ---------------------------------------------------------------------------
+
+# All 26 letters for consistent button count
+ALL_LETTERS = list("ABCDEFGHIJKLMNOPQRSTUVWXYZ")
+
+
+def get_letter_button_updates(state: Dict[str, Any]) -> List[gr.Button]:
+    """Generate button updates for all 26 letter buttons."""
+    puzzle_letters = set(state.get("puzzle_letters", []))
+    used_letters = set(state.get("free_letters", []))
+    letters_used = state.get("free_letters_used", 0)
+    can_select = letters_used < MAX_FREE_LETTERS
+
+    updates = []
+    for letter in ALL_LETTERS:
+        in_puzzle = letter in puzzle_letters
+        is_used = letter in used_letters
+
+        if not in_puzzle:
+            # Letter not in puzzle - hide it
+            updates.append(gr.Button(
+                value=letter,
+                visible=False,
+                interactive=False
+            ))
+        elif is_used:
+            # Letter already used
+            updates.append(gr.Button(
+                value=letter,
+                visible=True,
+                variant="secondary",
+                interactive=False,
+                elem_classes=["letter-btn-used"]
+            ))
+        else:
+            # Letter available
+            updates.append(gr.Button(
+                value=letter,
+                visible=True,
+                variant="primary",
+                interactive=can_select,
+                elem_classes=["letter-btn-available"]
+            ))
+    return updates
+
+
+def build_ui_outputs(state: Dict[str, Any], audio_html: str = "") -> tuple:
+    """Build the complete UI output tuple for all handlers.
+
+    Returns: (48 grid buttons, 26 letter buttons, score_panel, status_msg, audio, game_over, free_letter_status, state)
+    """
+    grid_button_updates = get_all_button_updates(state)
+    letter_button_updates = get_letter_button_updates(state)
+
+    return (
+        *grid_button_updates,  # 48 grid button updates
+        *letter_button_updates,  # 26 letter button updates
+        render_score_panel_html(state),
+        state.get("last_action", ""),
+        audio_html,
+        render_game_over_html(state),
+        render_free_letters_status(state),
+        state
+    )
+
+
+def ensure_state(state: Dict[str, Any]) -> Dict[str, Any]:
+    """Ensure state is a dict, not the initializer function."""
+    if callable(state):
+        return state()
+    return state
+
+
+def handle_cell_click(row: int, col: int, state: Dict[str, Any]) -> tuple:
+    """Handle grid cell click."""
+    state = ensure_state(state)
+    if state.get("game_over"):
+        return build_ui_outputs(state)
+
+    # Check if free letters required first
+    if state["free_letters_used"] < MAX_FREE_LETTERS:
+        state["last_action"] = f"Please choose {MAX_FREE_LETTERS - state['free_letters_used']} more free letter(s) first."
+        return build_ui_outputs(state)
+
+    coord = Coord(row, col)
+
+    # Convert to GameState for logic operations
+    gs, letter_map = state_to_gamestate(state)
+
+    # Check if cell has a letter (for sound effect)
+    has_letter = coord in letter_map
+
+    # Reveal the cell
+    reveal_cell(gs, letter_map, coord)
+    auto_mark_completed_words(gs)
+
+    # Update state dict
+    state = gamestate_to_dict(gs, state)
+
+    # Set sound effect
+    state["pending_sound"] = "hit" if has_letter else "miss"
+    audio_html = render_pending_audio_html(state)
+
+    return build_ui_outputs(state, audio_html)
+
+
+def handle_free_letter(letter: str, state: Dict[str, Any]) -> tuple:
+    """Handle free letter selection from dropdown."""
+    state = ensure_state(state)
+    if not letter or state.get("game_over"):
+        return build_ui_outputs(state)
+
+    letter = letter.upper().strip()
+    if len(letter) != 1 or not letter.isalpha():
+        state["last_action"] = "Invalid letter selection"
+        return build_ui_outputs(state)
+
+    # Check if already at max free letters
+    if state.get("free_letters_used", 0) >= MAX_FREE_LETTERS:
+        state["last_action"] = "Already used both free letters. Click cells to reveal more."
+        return build_ui_outputs(state)
+
+    # Convert to GameState for logic operations
+    gs, letter_map = state_to_gamestate(state)
+
+    # Count how many letters will be revealed
+    count_before = len(gs.revealed)
+
+    # Reveal free letter
+    reveal_free_letter(gs, letter_map, letter)
+    auto_mark_completed_words(gs)
+
+    # Check if any letters were revealed
+    count_after = len(gs.revealed)
+    revealed_count = count_after - count_before
+
+    # Update state dict
+    state = gamestate_to_dict(gs, state)
+
+    # Set sound effect
+    state["pending_sound"] = "hit" if revealed_count > 0 else "miss"
+    audio_html = render_pending_audio_html(state)
+
+    return build_ui_outputs(state, audio_html)
+
+
+def build_guess_outputs(state: Dict[str, Any], audio_html: str = "", clear_input: bool = False) -> tuple:
+    """Build UI outputs for guess handler (includes guess input clear)."""
+    grid_button_updates = get_all_button_updates(state)
+    letter_button_updates = get_letter_button_updates(state)
+
+    return (
+        *grid_button_updates,  # 48 grid button updates
+        *letter_button_updates,  # 26 letter button updates
+        render_score_panel_html(state),
+        state.get("last_action", ""),
+        "" if clear_input else gr.update(),  # guess input - clear or no change
+        audio_html,
+        render_game_over_html(state),
+        render_free_letters_status(state),
+        state
+    )
+
+
+def handle_guess(guess_text: str, state: Dict[str, Any]) -> tuple:
+    """Handle word guess submission."""
+    state = ensure_state(state)
+    if not guess_text or state.get("game_over"):
+        return build_guess_outputs(state, "", True)
+
+    guess_text = guess_text.strip().upper()
+
+    # Convert to GameState for logic operations
+    gs, letter_map = state_to_gamestate(state)
+
+    # Try to guess
+    success, points = guess_word(gs, guess_text)
+
+    if not success:
+        # Track incorrect guess
+        if guess_text not in state["incorrect_guesses"]:
+            state["incorrect_guesses"].append(guess_text)
+            if len(state["incorrect_guesses"]) > 10:
+                state["incorrect_guesses"] = state["incorrect_guesses"][-10:]
+
+    auto_mark_completed_words(gs)
+
+    # Update state dict
+    state = gamestate_to_dict(gs, state)
+
+    # Set sound effect
+    if success:
+        state["pending_sound"] = "correct_guess"
+    else:
+        state["pending_sound"] = "incorrect_guess"
+
+    # Check for game over - play congratulations
+    if state["game_over"]:
+        state["pending_sound"] = "congratulations"
+
+    audio_html = render_pending_audio_html(state)
+
+    return build_guess_outputs(state, audio_html, True)
+
+
+def handle_new_game(
+    wordlist: str,
+    game_mode: str,
+    sfx_enabled: bool,
+    sfx_volume: int,
+    music_enabled: bool,
+    music_volume: int,
+    state: Dict[str, Any]
+) -> tuple:
+    """Handle new game creation."""
+    state = ensure_state(state)
+    new_state = create_new_game_state(wordlist=wordlist, game_mode=game_mode)
+
+    # Preserve audio settings from UI components
+    new_state["sound_effects_enabled"] = sfx_enabled
+    new_state["sound_effects_volume"] = sfx_volume
+    new_state["music_enabled"] = music_enabled
+    new_state["music_volume"] = music_volume
+
+    return build_ui_outputs(new_state)
+
+
+def handle_audio_settings_change(
+    sfx_enabled: bool,
+    sfx_volume: int,
+    music_enabled: bool,
+    music_volume: int,
+    state: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Handle audio settings changes."""
+    state = ensure_state(state)
+
+    # Create a deep copy to ensure Gradio detects the change
+    new_state = copy.deepcopy(state)
+    new_state["sound_effects_enabled"] = sfx_enabled
+    new_state["sound_effects_volume"] = sfx_volume
+    new_state["music_enabled"] = music_enabled
+    new_state["music_volume"] = music_volume
+    return new_state
+
+
+# ---------------------------------------------------------------------------
+# Main App Creation
+# ---------------------------------------------------------------------------
+
+def create_app() -> gr.Blocks:
+    """Create the Gradio Blocks application."""
+
+    # Get available wordlists
+    wordlist_files = get_wordlist_files()
+    if not wordlist_files:
+        wordlist_files = ["classic.txt"]
+
+    # CSS file path
+    css_path = os.path.join(os.path.dirname(os.path.dirname(__file__)), "style_wrdler.css")
+
+    with gr.Blocks(
+        css=css_path if os.path.exists(css_path) else None,
+        theme="Surn/beeuty",
+        title=f"Wrdler v{__version__}"
+    ) as demo:
+
+        # Game state
+        game_state = gr.State(value=create_new_game_state)
+
+        # Header
+        gr.Markdown(f"# Wrdler v{__version__}")
+        gr.Markdown("Find all 6 hidden words in the 8×6 grid!")
+
+        # Tab layout
+        with gr.Tabs():
+            # Game Tab
+            with gr.TabItem("Game"):
+                with gr.Row():
+                    # Left column - Game area
+                    with gr.Column(scale=5):
+                        # Challenge mode leaderboard (if in challenge mode)
+                        challenge_leaderboard_html = gr.HTML(
+                            value="",
+                            elem_id="challenge-leaderboard-container"
+                        )
+
+                        # Free letter selection using button grid
+                        free_letter_status = gr.Markdown(
+                            value="Choose 2 free letters:",
+                            elem_id="free-letter-status"
+                        )
+                        # Create 26 letter buttons (only puzzle letters will be visible)
+                        letter_buttons: List[gr.Button] = []
+                        with gr.Row(elem_classes=["letter-buttons-row"]):
+                            for letter in ALL_LETTERS:
+                                btn = gr.Button(
+                                    value=letter,
+                                    variant="primary",
+                                    size="sm",
+                                    min_width=36,
+                                    visible=False,  # Will be shown for letters in puzzle
+                                    elem_classes=["letter-btn-available"],
+                                    elem_id=f"letter-{letter}"
+                                )
+                                letter_buttons.append(btn)
+
+                        # Game grid using native Gradio buttons
+                        # Create 48 buttons (6 rows x 8 cols) in a CSS grid
+                        grid_buttons: List[gr.Button] = []
+                        with gr.Group(elem_classes=["wrdler-grid-container"]):
+                            for row in range(GRID_ROWS):
+                                with gr.Row(elem_classes=["wrdler-grid-row"]):
+                                    for col in range(GRID_COLS):
+                                        btn = gr.Button(
+                                            value="?",
+                                            variant="primary",
+                                            size="sm",
+                                            min_width=50,
+                                            elem_classes=["grid-cell-unrevealed"],
+                                            elem_id=f"cell-{row}-{col}"
+                                        )
+                                        grid_buttons.append(btn)
+
+                        # Guess form
+                        with gr.Row():
+                            guess_input = gr.Textbox(
+                                label="Your Guess",
+                                placeholder="Enter a word...",
+                                max_lines=1,
+                                elem_id="guess-input"
+                            )
+                            guess_btn = gr.Button("Guess", variant="primary", elem_id="guess-btn")
+
+                        # Status message
+                        status_msg = gr.Markdown(value="Welcome! Choose your 2 free letters to start.")
+
+                        # Game over display
+                        game_over_html = gr.HTML(value="", elem_id="game-over-container")
+
+                    # Right column - Score panel and New Game
+                    with gr.Column(scale=3):
+                        # Score panel
+                        score_panel_html = gr.HTML(
+                            value=lambda: render_score_panel_html(create_new_game_state()),
+                            elem_id="score-panel-container"
+                        )
+                        # New Game button
+                        new_game_btn = gr.Button("New Game", variant="primary", size="lg")
+
+            # Settings Tab
+            with gr.TabItem("Settings"):
+                with gr.Row():
+                    with gr.Column():
+                        gr.Markdown("### Game Settings")
+                        wordlist_dropdown = gr.Dropdown(
+                            choices=wordlist_files,
+                            value=wordlist_files[0] if wordlist_files else "classic.txt",
+                            label="Word List"
+                        )
+                        game_mode_dropdown = gr.Dropdown(
+                            choices=["classic", "easy", "too easy"],
+                            value="classic",
+                            label="Game Mode"
+                        )
+
+                    with gr.Column():
+                        gr.Markdown("### Audio Settings")
+                        sfx_enabled = gr.Checkbox(
+                            value=True,
+                            label="Enable Sound Effects"
+                        )
+                        sfx_volume = gr.Slider(
+                            minimum=0,
+                            maximum=100,
+                            value=50,
+                            step=1,
+                            label="Sound Effects Volume"
+                        )
+                        music_enabled = gr.Checkbox(
+                            value=False,
+                            label="Enable Background Music"
+                        )
+                        music_volume = gr.Slider(
+                            minimum=0,
+                            maximum=100,
+                            value=30,
+                            step=1,
+                            label="Music Volume"
+                        )
+
+        # Hidden audio player for sound effects
+        audio_player_html = gr.HTML(value="", elem_id="audio-player", visible=False)
+
+        # Define common outputs for handlers
+        # Order: 48 grid buttons, 26 letter buttons, score_panel, status_msg, audio, game_over, free_letter_status, state
+        common_outputs = [
+            *grid_buttons,
+            *letter_buttons,
+            score_panel_html,
+            status_msg,
+            audio_player_html,
+            game_over_html,
+            free_letter_status,
+            game_state
+        ]
+
+        # Outputs for guess handler (includes guess_input clear)
+        guess_outputs = [
+            *grid_buttons,
+            *letter_buttons,
+            score_panel_html,
+            status_msg,
+            guess_input,  # Will be cleared
+            audio_player_html,
+            game_over_html,
+            free_letter_status,
+            game_state
+        ]
+
+        # Wire up each grid button to handle_cell_click
+        for idx, btn in enumerate(grid_buttons):
+            row = idx // GRID_COLS
+            col = idx % GRID_COLS
+            btn.click(
+                fn=partial(handle_cell_click, row, col),
+                inputs=[game_state],
+                outputs=common_outputs
+            )
+
+        # Wire up each letter button to handle_free_letter
+        for idx, btn in enumerate(letter_buttons):
+            letter = ALL_LETTERS[idx]
+            btn.click(
+                fn=partial(handle_free_letter, letter),
+                inputs=[game_state],
+                outputs=common_outputs
+            )
+
+        # Guess button and enter key
+        guess_btn.click(
+            fn=handle_guess,
+            inputs=[guess_input, game_state],
+            outputs=guess_outputs
+        )
+
+        guess_input.submit(
+            fn=handle_guess,
+            inputs=[guess_input, game_state],
+            outputs=guess_outputs
+        )
+
+        # New game button
+        new_game_btn.click(
+            fn=handle_new_game,
+            inputs=[wordlist_dropdown, game_mode_dropdown, sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
+            outputs=common_outputs
+        )
+
+        # Audio settings change handlers
+        sfx_enabled.change(
+            fn=handle_audio_settings_change,
+            inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
+            outputs=[game_state]
+        )
+        sfx_volume.change(
+            fn=handle_audio_settings_change,
+            inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
+            outputs=[game_state]
+        )
+        music_enabled.change(
+            fn=handle_audio_settings_change,
+            inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
+            outputs=[game_state]
+        )
+        music_volume.change(
+            fn=handle_audio_settings_change,
+            inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
+            outputs=[game_state]
+        )
+
+        # Initialize UI on app load
+        def initialize_ui(state):
+            """Initialize UI components on app load."""
+            state = ensure_state(state)
+            return build_ui_outputs(state)
+
+        demo.load(
+            fn=initialize_ui,
+            inputs=[game_state],
+            outputs=common_outputs
+        )
+
+    return demo