Switch to Gradio UI; Add MCP support

Transitioned Wrdler from Streamlit to Gradio as the primary UI framework, incorporating MCP (Model Context Protocol) server support for AI word generation. Updated README and deployment instructions to reflect these changes. Removed obsolete test scripts and added new ones for Gradio audio serving and MCP integration. Refactored audio handling to use a new shared core module. Incremented project version to 0.1.5.

LOCALHOST_PWA_README.md

@@ -1,269 +0,0 @@
-# PWA on Localhost - Important Information
-
-## Summary
-
-**The PWA files were created successfully**, but they **won't work fully on `localhost:8501`** due to Streamlit's static file serving limitations.
-
----
-
-## What You're Seeing (or Not Seeing)
-
-### ✅ What DOES Work on Localhost:
-
-1. **Game functionality**: Everything works normally
-2. **Challenge Mode**: Loading `?game_id=...` works (if HF credentials configured)
-3. **PWA meta tags**: Injected into HTML (check page source)
-4. **Service worker registration attempt**: Runs in browser console
-
-### ❌ What DOESN'T Work on Localhost:
-
-1. **`manifest.json` not accessible**:
-   ```
-   http://localhost:8501/app/static/manifest.json
-   → Returns HTML instead of JSON (Streamlit doesn't serve /app/static/)
-   ```
-
-2. **Icons not accessible**:
-   ```
-   http://localhost:8501/app/static/icon-192.png
-   → Returns 404 or HTML
-   ```
-
-3. **Service worker fails to register**:
-   ```javascript
-   // Browser console shows:
-   Failed to register service worker: 404 Not Found
-   ```
-
-4. **No PWA install prompt**:
-   - No banner at bottom of screen
-   - No install icon in address bar
-   - PWA features disabled
-
----
-
-## Why This Happens
-
-**Streamlit's Static File Serving:**
-
-- Streamlit only serves files from:
-  - `/.streamlit/static/` (internal Streamlit assets)
-  - Component assets via `declare_component()`
-  - NOT from arbitrary `battlewords/static/` directories
-
-- On HuggingFace Spaces:
-  - `/app/static/` is mapped by HF infrastructure
-  - Files in `battlewords/static/` are accessible at `/app/static/`
-  - ✅ PWA works perfectly
-
-- On localhost:
-  - No `/app/static/` mapping exists
-  - Streamlit returns HTML for all unrecognized paths
-  - ❌ PWA files return 404
-
----
-
-## How to Test PWA Locally
-
-### Option 1: Use ngrok (HTTPS Tunnel) ⭐ **RECOMMENDED**
-
-This is the **best way** to test PWA locally with full functionality:
-
-```bash
-# Terminal 1: Run Streamlit
-streamlit run app.py
-
-# Terminal 2: Expose with HTTPS
-ngrok http 8501
-
-# Output shows:
-# Forwarding https://abc123.ngrok-free.app -> http://localhost:8501
-```
-
-**Then visit the HTTPS URL on your phone or desktop:**
-- ✅ Full PWA functionality
-- ✅ Install prompt appears
-- ✅ manifest.json loads
-- ✅ Service worker registers
-- ✅ Icons display correctly
-
-**ngrok Setup:**
-1. Download: https://ngrok.com/download
-2. Sign up for free account
-3. Install: `unzip /path/to/ngrok.zip` (or chocolatey on Windows: `choco install ngrok`)
-4. Authenticate: `ngrok config add-authtoken <your-token>`
-5. Run: `ngrok http 8501`
-
----
-
-### Option 2: Deploy to HuggingFace Spaces ⭐ **PRODUCTION**
-
-PWA works out-of-the-box on HF Spaces:
-
-```bash
-git add wrdler/static/ wrdler/ui.py
-git commit -m "Add PWA support"
-git push
-
-# HF Spaces auto-deploys
-# Visit: https://[YourUsername]-wrdler.hf.space
-```
-
-**Then test PWA:**
-- Android Chrome: "Add to Home Screen" prompt appears
-- iOS Safari: Share → "Add to Home Screen"
-- Desktop Chrome: Install icon in address bar
-
-✅ **This is where PWA is meant to work!**
-
----
-
-###Option 3: Manual Static File Server (Advanced)
-
-You can serve the static files separately:
-
-```bash
-# Terminal 1: Run Streamlit
-streamlit run app.py
-
-# Terminal 2: Serve static files
-cd wrdler/static
-python3 -m http.server 8502
-
-# Then access:
-# Streamlit: http://localhost:8501
-# Static files: http://localhost:8502/manifest.json
-```
-
-**Then modify the PWA paths in `ui.py`:**
-```python
-pwa_meta_tags = """
-<link rel="manifest" href="http://localhost:8502/manifest.json">
-<link rel="apple-touch-icon" href="http://localhost:8502/icon-192.png">
-<!-- etc -->
-"""
-```
-
-❌ **Not recommended**: Too complex, defeats the purpose
-
----
-
-## What About Challenge Mode?
-
-**Question:** "I loaded `localhost:8501/?game_id=hDjsB_dl` but don't see anything"
-
-**Answer:** Challenge Mode is **separate from PWA**. You should see a blue banner at the top if:
-
-### ✅ Requirements for Challenge Mode to Work:
-
-1. **Environment variables configured** (`.env` file):
-   ```bash
-   HF_API_TOKEN=hf_xxxxxxxxxxxxx
-   HF_REPO_ID=Surn/Storage
-   SPACE_NAME=Surn/BattleWords
-   ```
-
-2. **Valid game_id exists** in the HF repo:
-   - `hDjsB_dl` must be a real challenge created previously
-   - Check HuggingFace dataset repo: https://huggingface.co/datasets/Surn/Storage
-   - Look for: `games/<uid>/settings.json`
-   - Verify `shortener.json` has entry for `hDjsB_dl`
-
-3. **Internet connection** (to fetch challenge data)
-
-### If Challenge Mode ISN'T Working:
-
-**Check browser console (F12 → Console):**
-```javascript
-// Look for errors:
-"[game_storage] Could not resolve sid: hDjsB_dl"  ← Challenge not found
-"Failed to load game from sid"                     ← HF API error
-"HF_API_TOKEN not configured"                      ← Missing credentials
-```
-
-**If you see errors:**
-1. Verify `.env` file exists with correct variables
-2. Restart Streamlit (`Ctrl+C` and `streamlit run app.py` again)
-3. Try a different `game_id` from a known challenge
-4. Check HF repo has the challenge data
-
-**Note:** Challenge Mode works the same in Wrdler as it did in BattleWords.
-
----
-
-## Summary Table
-
-| Feature | Localhost | Localhost + ngrok | HF Spaces (Production) |
-|---------|-----------|-------------------|------------------------|
-| **Game works** | ✅ | ✅ | ✅ |
-| **Challenge Mode** | ✅ (if .env configured) | ✅ | ✅ |
-| **PWA manifest loads** | ❌ | ✅ | ✅ |
-| **Service worker registers** | ❌ | ✅ | ✅ |
-| **Install prompt** | ❌ | ✅ | ✅ |
-| **Icons display** | ❌ | ✅ | ✅ |
-| **Full-screen mode** | ❌ | ✅ | ✅ |
-
----
-
-## What You Should Do
-
-### For Development:
-✅ **Just develop normally on localhost**
-- Game features work fine
-- Challenge Mode works (if .env configured)
-- PWA features won't work, but that's okay
-- Test PWA when you deploy
-
-### For PWA Testing:
-✅ **Use ngrok for quick local PWA testing**
-- 5 minutes to setup
-- Full PWA functionality
-- Test on real phone
-
-### For Production:
-✅ **Deploy to HuggingFace Spaces**
-- PWA works automatically
-- No configuration needed
-- `/app/static/` path works out-of-the-box
-
----
-
-## Bottom Line
-
-**Your question:** "Should I see something at the bottom of the screen?"
-
-**Answer:**
-
-1. **PWA install prompt**: ❌ Not on `localhost:8501` (Streamlit limitation)
-   - **Will work** on HF Spaces production deployment ✅
-   - **Will work** with ngrok HTTPS tunnel ✅
-
-2. **Challenge Mode banner**: ✅ Should appear at TOP (not bottom)
-   - Check if `?game_id=hDjsB_dl` exists in your HF repo
-   - Check browser console for errors
-   - Verify `.env` has `HF_API_TOKEN` configured
-
-The PWA implementation is **correct** and **ready for production**. It just won't work on bare localhost due to Streamlit's static file serving limitations. Once you deploy to HuggingFace Spaces, everything will work perfectly!
-
----
-
-## Quick Test Command
-
-```bash
-# Check if .env is configured:
-cat .env | grep HF_
-
-# Should show:
-# HF_API_TOKEN=hf_xxxxx
-# HF_REPO_ID=YourUsername/Storage
-# SPACE_NAME=YourUsername/Wrdler
-
-# If missing, Challenge Mode won't work locally
-```
-
----
-
-**Next Steps:**
-1. Test game functionality on localhost ✅
-2. Deploy to HF Spaces for PWA testing ✅
-3. Or install ngrok for local PWA testing ✅

README.md

@@ -6,396 +6,34 @@ colorTo: indigo
 sdk: gradio
 sdk_version: 5.50.0
 python_version: 3.12.8
-app_port: 8501
-app_file: app.py
+app_port: 7860
+app_file: gradio_app.py
 suggested_hardware: cpu-basic
 pinned: false
 tags:
 - game
 - vocabulary
-- streamlit
 - gradio
 - education
 - ai
-short_description: Fast paced word guessing game with AI-generated word lists
+- mcp
+- mcp-server
+short_description: Fast paced word game with AI-generated word lists & MCP
 thumbnail: >-
   https://cdn-uploads.huggingface.co/production/uploads/6346595c9e5f0fe83fc60444/6rWS4AIaozoNMCbx9F5Rv.png
 ---
 
-# Wrdler
+# Wrdler - MCP Hackathon Edition 🎉
 
 > **This project is based on BattleWords, but adapted for a simpler word puzzle game with an 8x6 grid, horizontal words only, and free letter guesses at the start.**
 
-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.
-
-**Dual UI Support:** Play with Streamlit (default) or Gradio 5.50+ (alternative) - same great gameplay, your choice of framework!
-
-**🎮 Live Demo:** [Play on Hugging Face Spaces](https://huggingface.co/spaces/Surn/Wrdler)
-
-## Key Differences from BattleWords
-
-- **8x6 grid** (instead of 12x12) with **6 words total** (one per row)
-- **Horizontal words only** (no vertical placement)
-- **No scope/radar visualization**
-- **2 free letter guesses** at the start - choose letters to reveal all instances in the grid
-
-## Features
-
-### Core Gameplay
-- 8x6 grid with six hidden words (one per row, all horizontal)
-- **Word composition:** Each puzzle contains exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
-- Game starts with 2 free letter guesses; all instances of chosen letters are revealed
-- Reveal grid cells and guess words for points
-- Scoring tiers: Good (34–37), Great (38–41), Fantastic (42+)
-- Game ends when all words are guessed or all word letters are revealed
-- Incorrect guess history with tooltip and optional display (enabled by default)
-- 10 incorrect guess limit per game
-- Two game modes: Classic (chain guesses) and Too Easy (single guess per reveal)
-
-### Audio & Visuals
-- Ocean-themed gradient background with wave animations
-- Background music system (toggleable with volume control)
-- Sound effects for hits, misses, correct/incorrect guesses
-- Responsive UI built with Streamlit
-
-### AI Word Generation
-- **Topic-based word lists**: Generate custom word lists using AI for any theme
-- **Intelligent word expansion**: New AI-generated words automatically saved to local files
-  - Smart detection separates existing dictionary words from new AI words
-  - Only saves new words to prevent duplicates
-  - Automatic retry mechanism (up to 3 attempts) for insufficient word counts
-  - 1000-word file size limit prevents bloat
-  - Auto-sorted by length then alphabetically
-- **Dual generation modes**:
-  - **HF Space API** (primary): Uses Hugging Face Space when `USE_HF_WORDS=true`
-  - **Local transformers** (fallback): Falls back to local models if HF unavailable
-- **Fallback support**: Gracefully uses dictionary words if AI generation fails
-- **Guaranteed distribution**: Ensures exactly 25 words each of lengths 4, 5, and 6
-
-### Customization
-- Multiple word lists (classic, fourth_grade, wordlist)
-- Wordlist sidebar controls (picker + one-click sort)
-- Audio volume controls (music and effects separate)
-
-### ✅ Challenge Mode
-- **Shareable challenge links** via short URLs (`?game_id=<sid>`)
-- **Multi-user leaderboards** sorted by score and time
-- **Remote storage** via Hugging Face datasets
-- **Word list difficulty calculation** and display
-- **Submit results** to existing challenges or create new ones
-- **Top 5 leaderboard** display in Challenge Mode banner
-- **"Show Challenge Share Links" toggle** (default OFF) to control URL visibility
-- Each player gets different random words from the same wordlist
-
-### Deployment & Technical
-- **Dockerfile-based deployment** supported for Hugging Face Spaces and other container platforms
-- **Dual UI frameworks**: 
-  - **Streamlit 1.51.0** (default) - Feature-rich, session-state based
-  - **Gradio 5.50+** (alternative) - Modern, reactive components
-  - Reference: [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)
-- **Environment variables** for Challenge Mode (HF_API_TOKEN, HF_REPO_ID, SPACE_NAME)
-- Works offline without HF credentials (Challenge Mode features disabled gracefully)
-- Compatible with both local development and cloud deployment
-
-### Progressive Web App (PWA)
-- Installable on desktop and mobile from your browser
-- Includes `service worker` and `manifest.json` with basic offline caching of static assets
-- See `INSTALL_GUIDE.md` for platform-specific steps
-
-### Planned
-- Local persistent storage for personal game history
-- Personal high scores sidebar (offline-capable)
-- Player statistics tracking
-- Deterministic seed UI for custom puzzles
-
-## Challenge Mode & Leaderboard
-
-When playing a shared challenge (via a `game_id` link), the leaderboard displays all submitted results for that challenge. The leaderboard is **sorted by highest score (descending), then by fastest time (ascending)**. This means players with the most points appear at the top, and ties are broken by the shortest completion time.
-
-## Installation
-1. Clone the repository:
- ```
- git clone https://github.com/Oncorporation/Wrdler.git
- cd wrdler
- ```
-2. (Optional) Create and activate a virtual environment:
- ```
- python -m venv venv
- source venv/bin/activate # On Windows use `venv\Scripts\activate`
- ```
-3. Install dependencies: ( add --system if not using a virutal environment)
- ```
- uv pip install -r requirements.txt --link-mode=copy 
- ```
-
-
-## Running Wrdler
-
-You can run the app locally using either [uv](https://github.com/astral-sh/uv) or Streamlit directly:
-
-**Streamlit UI (default):**
-```bash
-uv run streamlit run app.py
-# or
-streamlit run app.py
-```
-
-**Gradio UI (alternative):**
-```bash
-python -m wrdler.gradio_ui
-# or run the Gradio demo file directly
-```
-
-Both interfaces provide the same gameplay experience with slightly different UI frameworks.
-
-### Dockerfile Deployment (Hugging Face Spaces and more)
-
-Wrdler supports containerized deployment using a `Dockerfile`. This is the recommended method for deploying to [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker) or any Docker-compatible environment.
-
-To deploy on Hugging Face Spaces:
-1. Add a `Dockerfile` to your repository root (see [Spaces Dockerfile guide](https://huggingface.co/docs/hub/spaces-sdks-docker)).
-2. Push your code to your Hugging Face Space.
-3. The platform will build and run your app automatically.
-
-For local Docker runs:
-```sh
-docker build -t wrdler .
-docker run -p8501:8501 wrdler
-```
-
-### Environment Variables (for Challenge Mode)
-
-Challenge Mode requires a `.env` file in the project root with HuggingFace Hub credentials:
-
-```bash
-# Required for Challenge Mode
-HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx  # or HF_TOKEN
-HF_REPO_ID=YourUsername/YourRepo       # Target HF dataset repo
-SPACE_NAME=YourUsername/Wrdler         # Your HF Space name
-
-# Optional
-CRYPTO_PK=                             # Reserved for future signing
-```
-
-**How to get your HF_API_TOKEN:**
-1. Go to https://huggingface.co/settings/tokens
-2. Create a new token with `write` access
-3. Add to `.env` file as `HF_API_TOKEN=hf_...`
-
-**Note:** The app works without these variables, but Challenge Mode features (sharing, leaderboards) will be disabled.
-
-## Folder Structure
-
-- `app.py` – Streamlit entry point
-- `wrdler/` – Python package
- - `models.py` – data models and types
- - `word_loader.py` – word list loading and validation
- - `word_loader_ai.py` – AI word generation with HF Space API and local transformers
- - `generator.py` – word placement logic (8x6, horizontal only)
- - `logic.py` – game mechanics (reveal, guess, scoring, free letters)
- - `ui.py` – Streamlit UI composition
- - `gradio_ui.py` – Gradio UI implementation (alternative interface)
- - `game_storage.py` – Hugging Face remote storage integration and challenge sharing
- - `local_storage.py` – local JSON storage for results and high scores
- - `storage.py` – (legacy) local storage and high scores
- - `modules/` – shared utility modules (storage, constants, file_utils)
- - `words/` – word list files (classic.txt, fourth_grade.txt, wordlist.txt, AI-generated)
-- `style_wrdler.css` – Custom CSS styling for Gradio interface
-- `specs/` – documentation (`specs.md`, `requirements.md`)
-- `tests/` – unit tests
-
-## Test File Location
-All test files must be placed in the `/tests` folder. This ensures a clean project structure and makes it easy to discover and run all tests.
-
-## How to Play
-
-1. **Start with 2 free letter guesses** - choose two letters to reveal all their instances in the grid.
-2. Click grid squares to reveal letters or empty spaces.
-3. After revealing a letter, enter a guess for a word in the text box.
-4. Earn points for correct guesses and bonus points for unrevealed letters.
-5. **The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.**
-6. **To play a shared challenge, use a link with `?game_id=<sid>`. Your result will be added to the challenge leaderboard.**
-
-## Changelog
-
-### v0.1.2 (Current)
-- ✅ **Gradio UI Topic Display** - Prominent neon-styled badge at top of game area
-  - Glassmorphism background with glowing cyan border
-  - Pulsing neon animation effect
-  - Editable - type new topic and press Enter to generate/switch word lists
-- ✅ **Settings Persistence** - Enable Free Letters and Show Challenge Links persist across new games
-- ✅ **Timer Implementation** - Real-time game timer using gr.Timer component
-- ✅ **AI Topic Generation UI** - Added to Settings tab with Generate button
-- ✅ **Streamlit Cache Fix** - Conditional caching to avoid warnings in Gradio mode
-- ✅ **Enhanced CSS Styling** - Improved grid container, topic display, and responsive design
-
-### v0.1.1
-- ✅ Enhanced AI word generation with intelligent word saving
-- ✅ Automatic retry mechanism for insufficient word counts (up to 3 retries)
-- ✅ 1000-word file size limit to prevent dictionary bloat
-- ✅ Improved new word detection (separates existing vs. new words before saving)
-- ✅ Better HF Space API integration with graceful fallback to local models
-- ✅ Additional word generation when initial pass doesn't meet MIN_REQUIRED threshold
-- ✅ Enhanced logging for word generation pipeline visibility
-- ✅ **Gradio UI implementation** (gradio>=5.50) as alternative to Streamlit
-- ✅ Custom CSS styling for Gradio interface (style_wrdler.css)
-- ✅ Dual UI framework support - choose between Streamlit or Gradio
-
-### v0.1.0
-- ✅ AI word generation functionality added
-- ✅ Topic-based custom word list creation
-- ✅ Dual generation modes (HF Space API + local transformers)
-- ✅ Utility modules integration (storage, file_utils, constants)
-- ✅ Documentation synchronized across all files
-
-### v0.0.8
- - remove background animation
- - add "easy" mode (single guess per reveal)
-
-### v0.0.7 
- - fix guess bug - allowing guesses only after word guessed or letter revealed
-
-### v0.0.2 (Current - All Sprints Complete) 🎉
- - **Sprint 1-3:** Core data models, generator refactor, radar removal
- - **Sprint 4:** Implemented free letter selection UI with circular green gradient buttons
- - **Sprint 5:** Updated grid UI rendering for 8×6 display
- - **Sprint 6:** Comprehensive integration testing (7/7 tests passing)
- - **Sprint 7:** Complete documentation update
- - Sound effects integration for free letter selection
- - Mobile-responsive free letter grid
- - Fixed duplicate rendering call bug
- - **All core Wrdler features complete and tested**
-
-### v0.0.1 (Initial Wrdler Release)
- - Project renamed from BattleWords to Wrdler
- - Grid resized from 12x12 to 8x6
- - Changed to one word per row (6 total), horizontal only
- - Removed vertical word placement
- - Removed scope/radar visualization
- - Core data models updated for rectangular grid
- - Generator refactored for horizontal-only placement
-
-Note
-- `battlewords/storage.py` remains local-only storage; a separate HF integration wrapper is provided as `game_storage.py` for remote challenge mode.
-
-## Known Issues / TODO
-
-- Word list loading bug: the app may not select the proper word lists in some environments. Investigate `word_loader.get_wordlist_files()` / `load_word_list()` and sidebar selection to ensure the chosen file is correctly used by the generator.
-
-## Development Phases
-
-- **Proof of Concept (0.1.0):** No overlaps, basic UI, single session.
-- **Beta (0.5.0):** Overlaps allowed on shared letters, responsive layout, keyboard support, deterministic seed.
-- **Full (1.0.0):** Enhanced UX, persistence, leaderboards, daily/practice modes, advanced features.
-
-See `specs/requirements.md` and `specs/specs.md` for full details and roadmap.
-
-## License
-
-Wrdler is based on BattleWords. BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.
-
-## Hugging Face Spaces Configuration
-
-Wrdler is deployable as a Hugging Face Space with **dual UI support**: Streamlit (default) and Gradio (>=5.50). You can use either the YAML config block or a Dockerfile for advanced/custom deployments.
-
-To configure your Space with the YAML block, add it at the top of your `README.md`:
-
-**Streamlit Configuration (default):**
-```yaml
----
-title: Wrdler
-emoji: 🎲
-colorFrom: blue
-colorTo: indigo
-sdk: streamlit
-sdk_version: 1.51.0
-python_version: 3.12.8
-app_file: app.py
-suggested_hardware: cpu-basic
-tags:
- - game
- - vocabulary
- - streamlit
- - education
- - ai
----
-```
-
-**Gradio Configuration (alternative):**
-```yaml
----
-title: Wrdler Gradio
-emoji: 🎲
-colorFrom: blue
-colorTo: indigo
-sdk: gradio
-sdk_version: 5.50
-python_version: 3.12.8
-app_file: wrdler/gradio_ui.py
-suggested_hardware: cpu-basic
-tags:
- - game
- - vocabulary
- - gradio
- - education
- - ai
----
-```
-
-**Key parameters:**
-- `title`, `emoji`, `colorFrom`, `colorTo`: Visuals for your Space.
-- `sdk`: Use `streamlit` or `gradio` depending on your preferred UI framework.
-- `sdk_version`: Latest supported version (Streamlit 1.51.0 or Gradio 5.50+).
-- `python_version`: Python version (3.12.8 recommended).
-- `app_file`: Entry point for your app (`app.py` for Streamlit, `wrdler/gradio_ui.py` for Gradio).
-- `suggested_hardware`: Recommended hardware tier (cpu-basic is sufficient).
-- `tags`: List of descriptive tags.
-
-**Gradio Implementation Notes:**
-- Uses modern Gradio 5.50+ API (compatible with upcoming Gradio 6)
-- Reference: [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)
-- Custom styling via `style_wrdler.css`
-- State management with `gr.State` and deep copy updates
-- Event handlers use `.click()`, `.change()`, `.submit()` methods
-- Modal dialogs with `gr.Modal(visible=False)` pattern
-
-````````
-
-# Response
-````````markdown
----
-title: Wrdler
-emoji: 🎲
-colorFrom: blue
-colorTo: indigo
-sdk: streamlit
-sdk_version: 1.51.0
-python_version: 3.12.8
-app_port: 8501
-app_file: app.py
-suggested_hardware: cpu-basic
-pinned: false
-tags:
-- game
-- vocabulary
-- streamlit
-- gradio
-- education
-- ai
-short_description: Fast paced word guessing game with AI-generated word lists
-thumbnail: >-
-  https://cdn-uploads.huggingface.co/production/uploads/6346595c9e5f0fe83fc60444/6rWS4AIaozoNMCbx9F5Rv.png
----
-
-# Wrdler
-
-> **This project is based on BattleWords, but adapted for a simpler word puzzle game with an 8x6 grid, horizontal words only, and free letter guesses at the start.**
+> **🏆 MCP Hackathon Entry:** This Gradio version includes full MCP (Model Context Protocol) server support for AI word generation! See [MCP Integration Guide](docs/MCP_INTEGRATION.md) for details.
 
 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.
 
-**Dual UI Support:** Play with Streamlit (default) or Gradio 5.50+ (alternative) - same great gameplay, your choice of framework!
+**🎮 Live Demo:** [Play on Hugging Face Spaces](https://huggingface.co/spaces/MCP-1st-Birthday/wrdler)
 
-**🎮 Live Demo:** [Play on Hugging Face Spaces](https://huggingface.co/spaces/Surn/Wrdler)
+**🔧 MCP Server:** This version exposes AI word generation as an MCP tool for LLM integration!
 
 ## Key Differences from BattleWords
 
@@ -436,6 +74,8 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
   - **Local transformers** (fallback): Falls back to local models if HF unavailable
 - **Fallback support**: Gracefully uses dictionary words if AI generation fails
 - **Guaranteed distribution**: Ensures exactly 25 words each of lengths 4, 5, and 6
+- **MCP Integration**: Expose AI word generation as MCP tool when running locally
+  - See [MCP Integration Guide](docs/MCP_INTEGRATION.md) for setup and usage
 
 ### Customization
 - Multiple word lists (classic, fourth_grade, wordlist)
@@ -505,13 +145,16 @@ uv run streamlit run app.py
 streamlit run app.py
 ```
 
-**Gradio UI (alternative):**
+**Gradio UI (MCP-enabled for hackathon):**
 ```bash
+python gradio_app.py
+# or
 python -m wrdler.gradio_ui
-# or run the Gradio demo file directly
+
+# MCP server will be enabled automatically when USE_HF_WORDS=false
 ```
 
-Both interfaces provide the same gameplay experience with slightly different UI frameworks.
+Both interfaces provide the same gameplay experience with slightly different UI frameworks. **The Gradio version includes MCP server support for AI tool integration.**
 
 ### Dockerfile Deployment (Hugging Face Spaces and more)
 
@@ -583,7 +226,12 @@ All test files must be placed in the `/tests` folder. This ensures a clean proje
 
 ## Changelog
 
-### v0.1.2 (Current)
+### v0.1.2 (Current - MCP Hackathon Edition)
+- ✅ **MCP Server Integration** - Expose AI word generation as MCP tool 🏆
+  - `@gr.mcp_server_function` decorator for `generate_ai_words`
+  - Conditional registration based on `USE_HF_WORDS` flag
+  - Full schema documentation for inputs/outputs
+  - See [MCP Integration Guide](docs/MCP_INTEGRATION.md) for setup
 - ✅ **Gradio UI Topic Display** - Prominent neon-styled badge at top of game area
   - Glassmorphism background with glowing cyan border
   - Pulsing neon animation effect

check_audio_setup.py

@@ -1,109 +0,0 @@
-#!/usr/bin/env python3
-"""
-Diagnostic script to check audio setup for Wrdler Gradio UI.
-Run this to verify audio files and directories are properly configured.
-"""
-
-import os
-from pathlib import Path
-
-def check_audio_setup():
-    """Check if audio directories and files exist."""
-    print("=" * 70)
-    print("Wrdler Audio Setup Diagnostic")
-    print("=" * 70)
-    
-    wrdler_dir = Path(__file__).parent / "wrdler"
-    
-    # Check music directory
-    music_dir = wrdler_dir / "assets" / "audio" / "music"
-    print(f"\n?? Music Directory: {music_dir}")
-    if music_dir.exists():
-        print("   ? Directory exists")
-        music_files = list(music_dir.glob("*.mp3"))
-        if music_files:
-            print(f"   ?? Found {len(music_files)} MP3 file(s):")
-            for f in music_files:
-                size_kb = f.stat().st_size / 1024
-                print(f"      - {f.name} ({size_kb:.1f} KB)")
-        else:
-            print("   ??  No MP3 files found")
-    else:
-        print("   ? Directory does NOT exist")
-        print(f"   ?? Create it with: mkdir -p {music_dir}")
-    
-    # Check effects directory
-    effects_dir = wrdler_dir / "assets" / "audio" / "effects"
-    print(f"\n?? Sound Effects Directory: {effects_dir}")
-    if effects_dir.exists():
-        print("   ? Directory exists")
-        
-        required_effects = ["correct_guess", "incorrect_guess", "hit", "miss", "congratulations"]
-        found_effects = []
-        missing_effects = []
-        
-        for effect in required_effects:
-            mp3_file = effects_dir / f"{effect}.mp3"
-            wav_file = effects_dir / f"{effect}.wav"
-            
-            if mp3_file.exists():
-                size_kb = mp3_file.stat().st_size / 1024
-                found_effects.append(f"{effect}.mp3 ({size_kb:.1f} KB)")
-            elif wav_file.exists():
-                size_kb = wav_file.stat().st_size / 1024
-                found_effects.append(f"{effect}.wav ({size_kb:.1f} KB)")
-            else:
-                missing_effects.append(effect)
-        
-        if found_effects:
-            print(f"   ?? Found {len(found_effects)} effect file(s):")
-            for f in found_effects:
-                print(f"      - {f}")
-        
-        if missing_effects:
-            print(f"   ??  Missing {len(missing_effects)} effect file(s):")
-            for f in missing_effects:
-                print(f"      - {f}.mp3 or {f}.wav")
-    else:
-        print("   ? Directory does NOT exist")
-        print(f"   ?? Create it with: mkdir -p {effects_dir}")
-    
-    # Summary
-    print("\n" + "=" * 70)
-    print("Summary:")
-    print("=" * 70)
-    
-    all_ok = True
-    
-    if not music_dir.exists() or not list(music_dir.glob("*.mp3")):
-        print("??  Background music will not work (no music files found)")
-        all_ok = False
-    else:
-        print("? Background music should work")
-    
-    if not effects_dir.exists():
-        print("? Sound effects will not work (effects directory missing)")
-        all_ok = False
-    else:
-        required_effects = ["correct_guess", "incorrect_guess", "hit", "miss", "congratulations"]
-        missing_count = sum(1 for e in required_effects 
-                          if not (effects_dir / f"{e}.mp3").exists() 
-                          and not (effects_dir / f"{e}.wav").exists())
-        if missing_count > 0:
-            print(f"??  Sound effects partially working ({missing_count} missing)")
-            all_ok = False
-        else:
-            print("? All sound effects should work")
-    
-    if all_ok:
-        print("\n?? Audio setup is complete!")
-    else:
-        print("\n?? To generate missing sound effects, run:")
-        print("   python wrdler/sounds.py")
-        print("   or")
-        print("   python wrdler/generate_sounds.py")
-    
-    print("=" * 70)
-
-if __name__ == "__main__":
-    check_audio_setup()

docs/MCP_INTEGRATION.md

@@ -0,0 +1,280 @@
+# MCP Integration for Wrdler
+
+## Overview
+
+Wrdler exposes AI word generation functionality as an **MCP (Model Context Protocol) tool** when running locally. This allows AI assistants and other MCP clients to generate vocabulary words for custom topics.
+
+## What is MCP?
+
+The Model Context Protocol (MCP) is a standard for integrating AI assistants with external tools and data sources. Gradio 5.0+ has built-in MCP server support, making it easy to expose functions as MCP tools.
+
+**Reference:** [Building MCP Server with Gradio](https://www.gradio.app/guides/building-mcp-server-with-gradio)
+
+## Available MCP Tools
+
+### `generate_ai_words`
+
+Generate 75 AI-selected words (25 each of lengths 4, 5, 6) related to a specific topic.
+
+**Availability:** Only when running locally with `USE_HF_WORDS=false`
+
+#### Input Parameters
+
+```json
+{
+  "topic": "Ocean Life",          // Required: Theme for word generation
+  "model_name": null,              // Optional: Override default AI model
+  "seed": null,                    // Optional: Random seed for reproducibility
+  "use_dictionary_filter": true,  // Optional: Filter against dictionary (legacy parameter)
+  "selected_file": null            // Optional: Word list file for dictionary context
+}
+```
+
+#### Output Format
+
+```json
+{
+  "words": [
+    "WAVE", "TIDE", "FISH", ...    // 75 words total (25 � 4-letter, 25 � 5-letter, 25 � 6-letter)
+  ],
+  "difficulties": {
+    "WAVE": 0.45,                  // Difficulty score for each word
+    "TIDE": 0.32,
+    ...
+  },
+  "metadata": {
+    "model_used": "microsoft/Phi-3-mini-4k-instruct",
+    "transformers_available": "True",
+    "gradio_client_available": "True",
+    "use_hf_words": "False",
+    "raw_output_length": "2048",
+    "raw_output_snippet": "...",
+    "ai_initial_count": "75",
+    "topic": "Ocean Life",
+    "dictionary_filter": "True",
+    "new_words_saved": "15"
+  }
+}
+```
+
+## Setup
+
+### 1. Environment Configuration
+
+Set the `USE_HF_WORDS` environment variable to enable local mode:
+
+```bash
+# Linux/Mac
+export USE_HF_WORDS=false
+
+# Windows (PowerShell)
+$env:USE_HF_WORDS="false"
+
+# .env file
+USE_HF_WORDS=false
+```
+
+### 2. Run Gradio App
+
+```bash
+python gradio_app.py
+```
+
+You should see:
+
+```
+===========================================================================
+?? MCP SERVER ENABLED (Local Mode)
+===========================================================================
+MCP tools available:
+  - generate_ai_words: Generate AI vocabulary words for topics
+
+To use MCP tools, connect your MCP client to this Gradio app.
+See: https://www.gradio.app/guides/building-mcp-server-with-gradio
+===========================================================================
+```
+
+### 3. Connect MCP Client
+
+Configure your MCP client to connect to the Gradio server:
+
+```json
+{
+  "mcpServers": {
+    "wrdler": {
+      "url": "http://localhost:7860",
+      "transport": "gradio"
+    }
+  }
+}
+```
+
+## Usage Examples
+
+### Example 1: Basic Topic Generation
+
+**Input:**
+```json
+{
+  "topic": "Space Exploration"
+}
+```
+
+**Output:**
+```json
+{
+  "words": [
+    "STAR", "MARS", "MOON", "SHIP", "ORBIT", "COMET", ...
+  ],
+  "difficulties": {
+    "STAR": 0.25,
+    "MARS": 0.30,
+    ...
+  },
+  "metadata": {
+    "model_used": "microsoft/Phi-3-mini-4k-instruct",
+    "topic": "Space Exploration",
+    "ai_initial_count": "75",
+    ...
+  }
+}
+```
+
+### Example 2: With Custom Model and Seed
+
+**Input:**
+```json
+{
+  "topic": "Medieval History",
+  "model_name": "meta-llama/Llama-3.1-8B-Instruct",
+  "seed": 42
+}
+```
+
+### Example 3: Using MCP via Claude Desktop
+
+If you have Claude Desktop configured with MCP:
+
+1. Add Wrdler to your MCP configuration
+2. In Claude, use natural language:
+
+```
+Can you generate vocabulary words about Ancient Rome using the generate_ai_words tool?
+```
+
+Claude will automatically call the MCP tool and return the results.
+
+## Technical Details
+
+### Implementation
+
+The MCP integration is implemented in `wrdler/word_loader_ai.py` using Gradio's `@gr.mcp_server_function` decorator:
+
+```python
+@gr.mcp_server_function(
+    name="generate_ai_words",
+    description="Generate 75 AI-selected words...",
+    input_schema={...},
+    output_schema={...}
+)
+def mcp_generate_ai_words(...) -> dict:
+    # Wrapper for generate_ai_words()
+    ...
+```
+
+The Gradio app (`gradio_app.py`) enables the MCP server by setting `mcp_server=True` in the launch configuration:
+
+```python
+demo.launch(
+    server_name="0.0.0.0",
+    server_port=7860,
+    mcp_server=True,  # Enable MCP server
+    ...
+)
+```
+
+### Conditional Registration
+
+The MCP function is **only registered when**:
+- ? Gradio is available
+- ? `USE_HF_WORDS=false` (local mode)
+
+When deployed to Hugging Face Spaces (`USE_HF_WORDS=true`), the MCP function is **not registered** to avoid conflicts with the remote API.
+
+### Word Generation Pipeline
+
+1. **AI Generation**: Use local transformers models or HF Space API
+2. **Validation**: Filter words to lengths 4, 5, 6 (uppercase A-Z only)
+3. **Distribution**: Ensure 25 words per length
+4. **Difficulty Scoring**: Calculate word difficulty metrics
+5. **File Saving**: Save new words to topic-based files
+6. **Return**: Provide words, difficulties, and metadata
+
+## Troubleshooting
+
+### MCP Function Not Appearing
+
+**Check 1: Environment Variable**
+```bash
+echo $USE_HF_WORDS  # Should be "false"
+```
+
+**Check 2: Gradio Logs**
+```
+? word_loader_ai module loaded (MCP functions may be registered)
+? MCP server function 'generate_ai_words' registered (local mode)
+```
+
+**Check 3: Gradio Version**
+```bash
+pip show gradio  # Should be >= 5.0.0
+```
+
+### Model Loading Issues
+
+If you see warnings about model loading:
+```
+?? Transformers not available; falling back to dictionary words.
+```
+
+Install transformers:
+```bash
+pip install transformers torch
+```
+
+### Port Conflicts
+
+If port 7860 is in use, modify `gradio_app.py`:
+```python
+launch_kwargs = {
+    "server_port": 7861,  # Change port
+    ...
+}
+```
+
+## Remote vs Local Mode
+
+| Feature | Local Mode (`USE_HF_WORDS=false`) | Remote Mode (`USE_HF_WORDS=true`) |
+|---------|-----------------------------------|-----------------------------------|
+| MCP Server | ? Enabled | ? Disabled |
+| AI Models | Local transformers | HF Space API |
+| Word Saving | ? Saves to files | ? Saves to files |
+| Best For | Development, MCP clients | Production deployment |
+
+## Security Notes
+
+- MCP tools run with **full local file system access**
+- Only enable MCP server in **trusted environments**
+- Generated words are saved to `wrdler/words/` directory
+- Model weights are cached in `TMPDIR/hf-cache/`
+
+## Further Reading
+
+- [Gradio MCP Guide](https://www.gradio.app/guides/building-mcp-server-with-gradio)
+- [MCP Specification](https://modelcontextprotocol.io/)
+- [Wrdler Requirements](../specs/requirements.md)
+
+---
+
+**Last Updated:** 2025-11-30
+**Version:** 0.1.5

gradio_app.py

@@ -10,16 +10,99 @@ Usage:
     gradio gradio_app.py
 """
 
+import os
+import tempfile
+from pathlib import Path
 import gradio as gr
 from wrdler.gradio_ui import create_app
 
+# Import word_loader_ai to register MCP functions
+# This must happen before creating the app
+try:
+    from wrdler import word_loader_ai
+    print("? word_loader_ai module loaded (MCP functions may be registered)")
+except Exception as e:
+    print(f"?? Could not load word_loader_ai: {e}")
+
+# Get the project root directory (where this file is located)
+PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
+
+# Set the current working directory to project root
+# This ensures file paths are resolved correctly
+os.chdir(PROJECT_ROOT)
+
+print(f"Working Directory: {os.getcwd()}")
+print(f"Project Root: {PROJECT_ROOT}")
+
 # 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
-    )
+    # Configure paths for static assets
+    favicon_path = os.path.join(PROJECT_ROOT, "static", "favicon.ico")
+    
+    # Get Gradio's temp directory
+    gradio_temp_dir = Path(tempfile.gettempdir()) / "gradio"
+    
+    # Verify audio directory exists
+    audio_dir = os.path.join(PROJECT_ROOT, "wrdler", "assets", "audio")
+    print(f"Audio directory exists: {os.path.exists(audio_dir)}")
+    
+    if os.path.exists(audio_dir):
+        # List audio files for debugging
+        music_dir = os.path.join(audio_dir, "music")
+        effects_dir = os.path.join(audio_dir, "effects")
+        
+        if os.path.exists(music_dir):
+            music_files = [f for f in os.listdir(music_dir) if f.endswith('.mp3')]
+            print(f"Music files found: {music_files}")
+        
+        if os.path.exists(effects_dir):
+            effect_files = [f for f in os.listdir(effects_dir) if f.endswith('.mp3')]
+            print(f"Effect files found: {effect_files}")
+    
+    # Check MCP server status
+    use_hf_words = os.getenv("USE_HF_WORDS", "false").lower() == "true"
+    if not use_hf_words:
+        print("\n" + "="*70)
+        print("?? MCP SERVER ENABLED (Local Mode)")
+        print("="*70)
+        print("MCP tools available:")
+        print("  - generate_ai_words: Generate AI vocabulary words for topics")
+        print("\nTo use MCP tools, connect your MCP client to this Gradio app.")
+        print("See: https://www.gradio.app/guides/building-mcp-server-with-gradio")
+        print("="*70 + "\n")
+    else:
+        print("\n?? MCP server disabled (USE_HF_WORDS=true, running in remote mode)")
+    
+    # Launch configuration
+    launch_kwargs = {
+        "server_name": "0.0.0.0",
+        "server_port": 7860,
+        "share": False,
+        "show_error": True,
+        # Enable MCP server in local mode
+        "mcp_server": not use_hf_words,
+        # Gradio's allowed_paths should include:
+        # 1. Project root (for any relative paths)
+        # 2. System temp directory (where Gradio caches files)
+        "allowed_paths": [
+            PROJECT_ROOT,
+            str(gradio_temp_dir),
+            tempfile.gettempdir(),
+        ],
+    }
+    
+    # Add favicon if it exists
+    if os.path.exists(favicon_path):
+        launch_kwargs["favicon_path"] = favicon_path
+    
+    print(f"\nLaunching Gradio app...")
+    print(f"Allowed paths:")
+    for path in launch_kwargs['allowed_paths']:
+        print(f"  - {path}")
+    print(f"Server URL: http://localhost:7860")
+    if launch_kwargs["mcp_server"]:
+        print(f"MCP Server: ENABLED")
+    
+    demo.launch(**launch_kwargs)

pyproject.toml

@@ -1,11 +1,13 @@
 [project]
 name = "wrdler"
-version = "0.1.2"
-description = "Wrdler vocabulary puzzle game - simplified version based on BattleWords with 8x6 grid, horizontal words only, no scope, and 2 free letter guesses"
+version = "0.1.5"
+description = "Wrdler vocabulary puzzle game - simplified version based on BattleWords with 8x6 grid, horizontal words only, no scope, and 2 free letter guesses. Now with Gradio UI!"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"
 dependencies = [
     "streamlit>=1.51.0",
+    "gradio>=5.0.0",
+    "gradio-modal>=0.0.3",
     "matplotlib>=3.8",
     "requests>=2.31.0",
     "huggingface_hub>=0.20.0",
@@ -27,3 +29,5 @@ include = ["wrdler*"]
 
 [tool.setuptools.package-data]
 "wrdler.words" = ["*.txt"]
+"wrdler.assets.audio.music" = ["*.mp3"]
+"wrdler.assets.audio.effects" = ["*.mp3", "*.wav"]

test_gradio_audio_serving.py

@@ -0,0 +1,120 @@
+"""
+Test script to verify Gradio audio file serving.
+
+This creates a minimal Gradio app with HTML5 audio controls to test
+if audio files can be served via Gradio's /file= endpoint.
+"""
+
+import os
+import gradio as gr
+
+# Get project root
+PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
+
+# Audio file paths (absolute)
+MUSIC_FILE = os.path.join(PROJECT_ROOT, "wrdler", "assets", "audio", "music", "background.mp3")
+HIT_EFFECT = os.path.join(PROJECT_ROOT, "wrdler", "assets", "audio", "effects", "hit.mp3")
+MISS_EFFECT = os.path.join(PROJECT_ROOT, "wrdler", "assets", "audio", "effects", "miss.mp3")
+
+# Audio directory paths for allowed_paths
+MUSIC_DIR = os.path.join(PROJECT_ROOT, "wrdler", "assets", "audio", "music")
+EFFECTS_DIR = os.path.join(PROJECT_ROOT, "wrdler", "assets", "audio", "effects")
+
+print(f"Project Root: {PROJECT_ROOT}")
+print(f"Music file exists: {os.path.exists(MUSIC_FILE)}")
+print(f"Hit effect exists: {os.path.exists(HIT_EFFECT)}")
+print(f"Miss effect exists: {os.path.exists(MISS_EFFECT)}")
+print(f"Music dir exists: {os.path.exists(MUSIC_DIR)}")
+print(f"Effects dir exists: {os.path.exists(EFFECTS_DIR)}")
+
+# Convert to website-relative URLs (full path from website root)
+def get_file_url(absolute_path):
+    """Convert absolute path to /file= URL with full relative path from project root."""
+    # Get path relative to project root (website root)
+    rel_path = os.path.relpath(absolute_path, PROJECT_ROOT)
+    # Normalize to forward slashes for URLs
+    url_path = rel_path.replace(os.sep, '/')
+    return f"/gradio_api/file={url_path}"
+
+# Generate URLs with full relative paths from website root
+music_url = get_file_url(MUSIC_FILE)
+hit_url = get_file_url(HIT_EFFECT)
+miss_url = get_file_url(MISS_EFFECT)
+
+print(f"\nFile URLs (relative to website root):")
+print(f"Music: {music_url}")
+print(f"Hit: {hit_url}")
+print(f"Miss: {miss_url}")
+
+# Create HTML with audio controls using website-relative paths
+html_content = f"""
+<div style="padding: 20px; font-family: Arial, sans-serif;">
+    <h2>Gradio Audio File Serving Test (Full Relative Paths)</h2>
+    
+    <div style="margin: 20px 0; padding: 15px; background: #f0f0f0; border-radius: 5px;">
+        <h3>Background Music</h3>
+        <p><strong>Absolute path:</strong> {MUSIC_FILE}</p>
+        <p><strong>URL (from website root):</strong> {music_url}</p>
+        <audio controls style="width: 100%;">
+            <source src="{music_url}" type="audio/mpeg">
+            Your browser does not support audio.
+        </audio>
+    </div>
+    
+    <div style="margin: 20px 0; padding: 15px; background: #f0f0f0; border-radius: 5px;">
+        <h3>Hit Sound Effect</h3>
+        <p><strong>Absolute path:</strong> {HIT_EFFECT}</p>
+        <p><strong>URL (from website root):</strong> {hit_url}</p>
+        <audio controls style="width: 100%;">
+            <source src="{hit_url}" type="audio/mpeg">
+            Your browser does not support audio.
+        </audio>
+    </div>
+    
+    <div style="margin: 20px 0; padding: 15px; background: #f0f0f0; border-radius: 5px;">
+        <h3>Miss Sound Effect</h3>
+        <p><strong>Absolute path:</strong> {MISS_EFFECT}</p>
+        <p><strong>URL (from website root):</strong> {miss_url}</p>
+        <audio controls style="width: 100%;">
+            <source src="{miss_url}" type="audio/mpeg">
+            Your browser does not support audio.
+        </audio>
+    </div>
+    
+    <div style="margin: 20px 0; padding: 15px; background: #fff3cd; border-radius: 5px;">
+        <h3>Testing Instructions</h3>
+        <ol>
+            <li>Check the browser console for any 404 errors</li>
+            <li>Try playing each audio file using the controls</li>
+            <li>Check the Network tab to see if files load successfully</li>
+        </ol>
+        <p><strong>Note:</strong> Using full relative paths from website root (e.g., /file=wrdler/assets/audio/music/background.mp3)</p>
+    </div>
+</div>
+"""
+
+# Create Gradio interface
+with gr.Blocks(title="Audio Serving Test") as demo:
+    gr.HTML(html_content)
+
+if __name__ == "__main__":
+    # Configure allowed paths - include specific audio directories
+    launch_kwargs = {
+        "server_name": "0.0.0.0",
+        "server_port": 7861,  # Different port to avoid conflict
+        "share": False,
+        "show_error": True,
+        # Allow Gradio to serve files from these directories
+        "allowed_paths": [
+            PROJECT_ROOT,      # Project root (fallback)
+            MUSIC_DIR,         # wrdler/assets/audio/music
+            EFFECTS_DIR,       # wrdler/assets/audio/effects
+        ],
+    }
+    
+    print(f"\nLaunching test server on http://localhost:7861")
+    print(f"Allowed paths:")
+    for path in launch_kwargs['allowed_paths']:
+        print(f"  - {path}")
+    
+    demo.launch(**launch_kwargs)

test_mcp.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python
+"""
+Quick test script to verify MCP integration is working.
+
+This script:
+1. Checks if Gradio MCP dependencies are installed
+2. Verifies the MCP function registration
+3. Tests the generate_ai_words wrapper
+
+Usage:
+    python test_mcp.py
+"""
+
+import os
+import sys
+
+def test_gradio_mcp():
+    """Test Gradio MCP support."""
+    print("="*70)
+    print("Testing Gradio MCP Integration")
+    print("="*70)
+    
+    # Test 1: Check Gradio installation
+    print("\n1. Checking Gradio installation...")
+    try:
+        import gradio as gr
+        print(f"   ? Gradio version: {gr.__version__}")
+    except ImportError as e:
+        print(f"   ? Gradio not installed: {e}")
+        return False
+    
+    # Test 2: Check MCP dependencies
+    print("\n2. Checking MCP dependencies...")
+    try:
+        import mcp
+        print(f"   ? MCP package installed")
+    except ImportError:
+        print(f"   ?? MCP package not installed")
+        print(f"      Install with: pip install 'gradio[mcp]'")
+        # Not critical - continue anyway
+    
+    # Test 3: Check word_loader_ai module
+    print("\n3. Checking word_loader_ai module...")
+    try:
+        from wrdler import word_loader_ai
+        print(f"   ? word_loader_ai module loaded")
+        
+        # Check if MCP function exists
+        if hasattr(word_loader_ai, 'mcp_generate_ai_words'):
+            print(f"   ? MCP function 'mcp_generate_ai_words' registered")
+        else:
+            print(f"   ?? MCP function not registered (may be disabled by USE_HF_WORDS flag)")
+            
+    except ImportError as e:
+        print(f"   ? Failed to load word_loader_ai: {e}")
+        return False
+    
+    # Test 4: Check environment variables
+    print("\n4. Checking environment configuration...")
+    use_hf_words = os.getenv("USE_HF_WORDS", "false").lower() == "true"
+    print(f"   USE_HF_WORDS: {use_hf_words}")
+    
+    if use_hf_words:
+        print(f"   ?? MCP server will be DISABLED (remote mode)")
+    else:
+        print(f"   ? MCP server will be ENABLED (local mode)")
+    
+    # Test 5: Verify function can be called
+    print("\n5. Testing MCP function wrapper...")
+    try:
+        if hasattr(word_loader_ai, 'mcp_generate_ai_words'):
+            print(f"   ?? Function callable: mcp_generate_ai_words")
+            print(f"   ?? Note: Full test requires AI model (skipping actual generation)")
+        else:
+            print(f"   ?? Function not available (USE_HF_WORDS=true or Gradio not available)")
+    except Exception as e:
+        print(f"   ? Error testing function: {e}")
+    
+    print("\n" + "="*70)
+    print("MCP Integration Test Complete")
+    print("="*70)
+    print("\nTo enable MCP server:")
+    print("  1. Set USE_HF_WORDS=false in your environment")
+    print("  2. Run: python gradio_app.py")
+    print("  3. Connect your MCP client to http://localhost:7860")
+    print("\nFor detailed setup, see: docs/MCP_INTEGRATION.md")
+    
+    return True
+
+if __name__ == "__main__":
+    success = test_gradio_mcp()
+    sys.exit(0 if success else 1)

tests/test_apptest.py

@@ -1,7 +0,0 @@
-# file: D:/Projects/Battlewords/tests/test_apptest.py
-from streamlit.testing.v1 import AppTest
-
-def test_app_runs():
-    at = AppTest.from_file("app.py")
-    at.run()
-    assert not at.exception

tests/test_compare_difficulty_functions.py

@@ -1,237 +0,0 @@
-# file: tests/test_compare_difficulty_functions.py
-import os
-import sys
-import pytest
-
-# Ensure the modules path is available
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
-
-from wrdler.modules.constants import HF_API_TOKEN
-from wrdler.modules.storage import gen_full_url, _get_json_from_repo, HF_REPO_ID, SHORTENER_JSON_FILE
-from wrdler.word_loader import compute_word_difficulties, compute_word_difficulties2, compute_word_difficulties3
-
-# Ensure the token is set for Hugging Face Hub
-if HF_API_TOKEN:
-    os.environ["HF_API_TOKEN"] = HF_API_TOKEN
-
-# Define sample_words as a global variable
-sample_words = []
-
-def test_compare_difficulty_functions_for_challenge(capsys):
-    """
-    Compare compute_word_difficulties, compute_word_difficulties2, and compute_word_difficulties3
-    for all users in a challenge identified by short_id.
-    """
-    global sample_words  # Ensure we modify the global variable
-
-    # Use a fixed short id for testing
-    short_id = "hDjsB_dl"
-
-    # Step 1: Resolve short ID to full URL
-    status, full_url = gen_full_url(
-        short_url=short_id,
-        repo_id=HF_REPO_ID,
-        json_file=SHORTENER_JSON_FILE
-    )
-
-    if status != "success_retrieved_full" or not full_url:
-        print(
-            f"Could not resolve short id '{short_id}'. "
-            f"Status: {status}. "
-            f"Check repo '{HF_REPO_ID}' and mapping file '{SHORTENER_JSON_FILE}'."
-        )
-        captured = capsys.readouterr()
-        assert "Could not resolve short id" in captured.out
-        assert not full_url, "full_url should be empty/None on failure"
-        print("settings.json was not found or could not be resolved.")
-        return
-
-    print(f"✓ Resolved short id '{short_id}' to full URL: {full_url}")
-
-    # Step 2: Extract file path from full URL
-    url_parts = full_url.split("/resolve/main/")
-    assert len(url_parts) == 2, f"Invalid full URL format: {full_url}"
-    file_path = url_parts[1]
-
-    # Step 3: Download and parse settings.json
-    settings = _get_json_from_repo(HF_REPO_ID, file_path, repo_type="dataset")
-    assert settings, "Failed to download or parse settings.json"
-    print(f"✓ Downloaded settings.json")
-
-    # Validate settings structure
-    assert "challenge_id" in settings
-    assert "wordlist_source" in settings
-    assert "users" in settings
-    
-    wordlist_source = settings.get("wordlist_source", "wordlist.txt")
-    users = settings.get("users", [])
-    
-    print(f"\nChallenge ID: {settings['challenge_id']}")
-    print(f"Wordlist Source: {wordlist_source}")
-    print(f"Number of Users: {len(users)}")
-
-    # Step 4: Determine wordlist file path
-    # Assuming the wordlist is in battlewords/words/ directory
-    words_dir = os.path.join(os.path.dirname(__file__), "..", "battlewords", "words")
-    wordlist_path = os.path.join(words_dir, wordlist_source)
-    
-    # If wordlist doesn't exist, try classic.txt as fallback
-    if not os.path.exists(wordlist_path):
-        print(f"⚠ Wordlist '{wordlist_source}' not found, using 'classic.txt' as fallback")
-        wordlist_path = os.path.join(words_dir, "classic.txt")
-    
-    assert os.path.exists(wordlist_path), f"Wordlist file not found: {wordlist_path}"
-    print(f"✓ Using wordlist: {wordlist_path}")
-
-    # Step 5: Compare difficulty functions for each user
-    print("\n" + "="*80)
-    print("DIFFICULTY COMPARISON BY USER")
-    print("="*80)
-
-    all_results = []    
-
-    for user_idx, user in enumerate(users, 1):
-        user_name = user.get("name", f"User {user_idx}")
-        word_list = user.get("word_list", [])
-        sample_words += word_list  # Update the global variable with the latest word list
-        
-        if not word_list:
-            print(f"\n[{user_idx}] {user_name}: No words assigned, skipping")
-            continue
-
-        print(f"\n[{user_idx}] {user_name}")
-        print(f"     Words: {len(word_list)} words")
-        print(f"     Sample: {', '.join(word_list[:5])}{'...' if len(word_list) > 5 else ''}")
-
-        # Compute difficulties using all three functions
-        total_diff1, difficulties1 = compute_word_difficulties(wordlist_path, word_list)
-        total_diff2, difficulties2 = compute_word_difficulties2(wordlist_path, word_list)
-        total_diff3, difficulties3 = compute_word_difficulties3(wordlist_path, word_list)
-
-        print(f"\n     Function 1 (compute_word_difficulties):")
-        print(f"       Total Difficulty: {total_diff1:.4f}")
-        print(f"       Words Processed: {len(difficulties1)}")
-        
-        print(f"\n     Function 2 (compute_word_difficulties2):")
-        print(f"       Total Difficulty: {total_diff2:.4f}")
-        print(f"       Words Processed: {len(difficulties2)}")
-
-        print(f"\n     Function 3 (compute_word_difficulties3):")
-        print(f"       Total Difficulty: {total_diff3:.4f}")
-        print(f"       Words Processed: {len(difficulties3)}")
-
-        # Calculate statistics
-        if difficulties1 and difficulties2 and difficulties3:
-            avg_diff1 = total_diff1 / len(difficulties1)
-            avg_diff2 = total_diff2 / len(difficulties2)
-            avg_diff3 = total_diff3 / len(difficulties3)
-            
-            print(f"\n     Comparison:")
-            print(f"       Average Difficulty (Func1): {avg_diff1:.4f}")
-            print(f"       Average Difficulty (Func2): {avg_diff2:.4f}")
-            print(f"       Average Difficulty (Func3): {avg_diff3:.4f}")
-            print(f"       Difference (Func1 vs Func2): {abs(avg_diff1 - avg_diff2):.4f}")
-            print(f"       Difference (Func1 vs Func3): {abs(avg_diff1 - avg_diff3):.4f}")
-            print(f"       Difference (Func2 vs Func3): {abs(avg_diff2 - avg_diff3):.4f}")
-
-        # Store results for final summary
-        all_results.append({
-            "user_name": user_name,
-            "word_count": len(word_list),
-            "total_diff1": total_diff1,
-            "total_diff2": total_diff2,
-            "total_diff3": total_diff3,
-            "difficulties1": difficulties1,
-            "difficulties2": difficulties2,
-            "difficulties3": difficulties3,
-        })
-
-    # Step 6: Print summary comparison
-    print("\n" + "="*80)
-    print("OVERALL SUMMARY")
-    print("="*80)
-
-    if all_results:
-        total1_sum = sum(r["total_diff1"] for r in all_results)
-        total2_sum = sum(r["total_diff2"] for r in all_results)
-        total3_sum = sum(r["total_diff3"] for r in all_results)
-        total_words = sum(r["word_count"] for r in all_results)
-
-        print(f"\nTotal Users Analyzed: {len(all_results)}")
-        print(f"Total Words Across All Users: {total_words}")
-        print(f"\nAggregate Total Difficulty:")
-        print(f"  Function 1: {total1_sum:.4f}")
-        print(f"  Function 2: {total2_sum:.4f}")
-        print(f"  Function 3: {total3_sum:.4f}")
-        print(f"  Difference (Func1 vs Func2): {abs(total1_sum - total2_sum):.4f}")
-        print(f"  Difference (Func1 vs Func3): {abs(total1_sum - total3_sum):.4f}")
-        print(f"  Difference (Func2 vs Func3): {abs(total2_sum - total3_sum):.4f}")
-
-        # Validate that all functions returned results for all users
-        assert all(r["difficulties1"] for r in all_results), "Function 1 failed for some users"
-        assert all(r["difficulties2"] for r in all_results), "Function 2 failed for some users"
-        assert all(r["difficulties3"] for r in all_results), "Function 3 failed for some users"
-        
-        print("\n✓ All tests passed!")
-    else:
-        print("\n⚠ No users with words found in this challenge")
-
-
-def test_compare_difficulty_functions_with_classic_wordlist():
-    """
-    Test all three difficulty functions using the classic.txt wordlist
-    with a sample set of words.
-    """
-    global sample_words  # Use the global variable
-
-    words_dir = os.path.join(os.path.dirname(__file__), "..", "battlewords", "words")
-    wordlist_path = os.path.join(words_dir, "classic.txt")
-    
-    if not os.path.exists(wordlist_path):
-        pytest.skip(f"classic.txt not found at {wordlist_path}")
-    
-    # Use the global sample_words if already populated, otherwise set a default
-    if not sample_words:
-        sample_words = ["ABLE", "ACID", "AREA", "ARMY", "BEAR", "BOWL", "CAVE", "COIN", "ECHO", "GOLD"]
-    
-    print("\n" + "="*80)
-    print("TESTING WITH CLASSIC.TXT WORDLIST")
-    print("="*80)
-    print(f"Sample Words: {', '.join(sample_words)}")
-    
-    # Compute difficulties
-    total_diff1, difficulties1 = compute_word_difficulties(wordlist_path, sample_words)
-    total_diff2, difficulties2 = compute_word_difficulties2(wordlist_path, sample_words)
-    total_diff3, difficulties3 = compute_word_difficulties3(wordlist_path, sample_words)
-    
-    print(f"\nFunction compute_word_difficulties Results:")
-    print(f"  Total Difficulty: {total_diff1:.4f}")
-    for word in sample_words:
-        if word in difficulties1:
-            print(f"    {word}: {difficulties1[word]:.4f}")
-    
-    print(f"\nFunction compute_word_difficulties2 Results:")
-    print(f"  Total Difficulty: {total_diff2:.4f}")
-    for word in sample_words:
-        if word in difficulties2:
-            print(f"    {word}: {difficulties2[word]:.4f}")
-    
-    print(f"\nFunction compute_word_difficulties3 Results:")
-    print(f"  Total Difficulty: {total_diff3:.4f}")
-    for word in sample_words:
-        if word in difficulties3:
-            print(f"    {word}: {difficulties3[word]:.4f}")
-    
-    # Assertions
-    assert len(difficulties1) == len(set(sample_words)), "Function 1 didn't process all words"
-    assert len(difficulties2) == len(set(sample_words)), "Function 2 didn't process all words"
-    assert len(difficulties3) == len(set(sample_words)), "Function 3 didn't process all words"
-    assert total_diff1 > 0, "Function 1 total difficulty should be positive"
-    assert total_diff2 > 0, "Function 2 total difficulty should be positive"
-    assert total_diff3 > 0, "Function 3 total difficulty should be positive"
-    
-    print("\n✓ Classic wordlist test passed!")
-
-
-if __name__ == "__main__":
-    pytest.main(["-s", "-v", __file__])

tests/test_download_game_settings.py

@@ -1,63 +0,0 @@
-# file: tests/test_download_game_settings.py
-import os
-import sys
-import pytest
-
-# Ensure the modules path is available
-sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
-
-from wrdler.modules.constants import HF_API_TOKEN  # <-- Import the token
-from wrdler.modules.storage import gen_full_url, _get_json_from_repo, HF_REPO_ID, SHORTENER_JSON_FILE
-
-# Ensure the token is set for Hugging Face Hub
-if HF_API_TOKEN:
-    os.environ["HF_API_TOKEN"] = HF_API_TOKEN
-
-def test_download_settings_by_short_id_handles_both(capsys):
-    # Use a fixed short id for testing
-    short_id = "hDjsB_dl"
-
-    # Step 1: Resolve short ID to full URL
-    status, full_url = gen_full_url(
-        short_url=short_id,
-        repo_id=HF_REPO_ID,
-        json_file=SHORTENER_JSON_FILE
-    )
-
-    # Failure branch: provide a helpful message and assert expected failure shape
-    if status != "success_retrieved_full" or not full_url:
-        print(
-            f"Could not resolve short id '{short_id}'. "
-            f"Status: {status}. "
-            f"Check repo '{HF_REPO_ID}' and mapping file '{SHORTENER_JSON_FILE}'."
-        )
-        captured = capsys.readouterr()
-        assert "Could not resolve short id" in captured.out
-        # Ensure failure shape is consistent
-        assert not full_url, "full_url should be empty/None on failure"
-        print("settings.json was not found or could not be resolved.")
-        return
-    else:
-        print(f"Resolved short id '{short_id}' to full URL: {full_url}")
-
-    # Success branch
-    assert status == "success_retrieved_full", f"Failed to resolve short ID: {status}"
-    assert full_url, "No full URL returned"
-
-    # Step 2: Extract file path from full URL
-    url_parts = full_url.split("/resolve/main/")
-    assert len(url_parts) == 2, f"Invalid full URL format: {full_url}"
-    file_path = url_parts[1]
-
-    # Step 3: Download and parse settings.json
-    settings = _get_json_from_repo(HF_REPO_ID, file_path, repo_type="dataset")
-    assert settings, "Failed to download or parse settings.json"
-
-    print("\nDownloaded settings.json contents:", settings)
-    # Optionally, add more assertions about the settings structure
-    assert "challenge_id" in settings
-    assert "wordlist_source" in settings
-    assert "users" in settings
-
-if __name__ == "__main__":
-    pytest.main(["-s", __file__])

tests/test_generator.py

@@ -1,29 +0,0 @@
-import unittest
-
-from wrdler.generator import generate_puzzle, validate_puzzle
-from wrdler.models import Coord
-
-
-class TestGenerator(unittest.TestCase):
-    def test_generate_valid_puzzle(self):
-        # Provide a minimal word pool for deterministic testing
-        words_by_len = {
-            4: ["TREE", "BOAT"],
-            5: ["APPLE", "RIVER"],
-            6: ["ORANGE", "PYTHON"],
-        }
-        p = generate_puzzle(grid_size=12, words_by_len=words_by_len, seed=1234)
-        validate_puzzle(p, grid_size=12)
-        # Ensure 6 words and 6 radar pulses
-        self.assertEqual(len(p.words), 6)
-        self.assertEqual(len(p.radar), 6)
-        # Ensure no overlaps
-        seen = set()
-        for w in p.words:
-            for c in w.cells:
-                self.assertNotIn(c, seen)
-                seen.add(c)
-                self.assertTrue(0 <= c.x < 12 and 0 <= c.y < 12)
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_generator_wrdler.py

@@ -1,227 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-Quick test script for Wrdler puzzle generator.
-Tests the new horizontal-only, 6x8 grid generator.
-"""
-
-import sys
-import os
-
-# Force UTF-8 encoding on Windows
-if sys.platform == "win32":
-    import codecs
-    sys.stdout = codecs.getwriter("utf-8")(sys.stdout.detach())
-    sys.stderr = codecs.getwriter("utf-8")(sys.stderr.detach())
-
-from wrdler.generator import generate_puzzle, validate_puzzle
-from wrdler.word_loader import load_word_list
-
-def test_basic_generation():
-    """Test basic puzzle generation with default parameters."""
-    print("Test 1: Basic puzzle generation (6 rows × 8 columns)")
-    print("=" * 60)
-
-    try:
-        puzzle = generate_puzzle()
-        print(f"✓ Puzzle generated successfully!")
-        print(f"  Grid: {puzzle.grid_rows} rows × {puzzle.grid_cols} columns")
-        print(f"  Words: {len(puzzle.words)}")
-        print()
-
-        # Print words
-        print("Words in puzzle:")
-        for i, word in enumerate(sorted(puzzle.words, key=lambda w: w.start.x), 1):
-            print(f"  {i}. '{word.text}' ({len(word.text)} letters) - Row {word.start.x}, Cols {word.start.y}-{word.start.y + len(word.text) - 1}, Direction: {word.direction}")
-        print()
-
-        # Validate
-        validate_puzzle(puzzle, grid_rows=puzzle.grid_rows, grid_cols=puzzle.grid_cols)
-        print("✓ Puzzle validation passed!")
-        print()
-
-        return True
-    except Exception as e:
-        print(f"✗ Test failed: {e}")
-        import traceback
-        traceback.print_exc()
-        return False
-
-
-def test_with_seed():
-    """Test deterministic generation with seed."""
-    print("Test 2: Deterministic generation with seed")
-    print("=" * 60)
-
-    try:
-        puzzle1 = generate_puzzle(seed=12345)
-        puzzle2 = generate_puzzle(seed=12345)
-
-        # Should generate same words
-        words1 = [w.text for w in puzzle1.words]
-        words2 = [w.text for w in puzzle2.words]
-
-        if words1 == words2:
-            print(f"✓ Deterministic generation works!")
-            print(f"  Both puzzles have words: {words1}")
-            print()
-            return True
-        else:
-            print(f"✗ Deterministic generation failed!")
-            print(f"  Puzzle 1: {words1}")
-            print(f"  Puzzle 2: {words2}")
-            print()
-            return False
-    except Exception as e:
-        print(f"✗ Test failed: {e}")
-        import traceback
-        traceback.print_exc()
-        return False
-
-
-def test_target_words():
-    """Test generation with specific target words."""
-    print("Test 3: Generation with target words")
-    print("=" * 60)
-
-    target_words = ["CAT", "DOGS", "BIRDS", "FISH", "MONKEY", "ELEPHANT"]
-
-    try:
-        puzzle = generate_puzzle(target_words=target_words)
-        generated_words = sorted([w.text for w in puzzle.words])
-        expected_words = sorted([w.upper() for w in target_words])
-
-        if generated_words == expected_words:
-            print(f"✓ Target words generation works!")
-            print(f"  Generated: {generated_words}")
-            print()
-            return True
-        else:
-            print(f"✗ Target words generation failed!")
-            print(f"  Expected: {expected_words}")
-            print(f"  Got: {generated_words}")
-            print()
-            return False
-    except Exception as e:
-        print(f"✗ Test failed: {e}")
-        import traceback
-        traceback.print_exc()
-        return False
-
-
-def test_grid_visualization():
-    """Visualize a generated puzzle on the grid."""
-    print("Test 4: Grid visualization")
-    print("=" * 60)
-
-    try:
-        puzzle = generate_puzzle(seed=42)
-
-        # Create 6x8 grid
-        grid = [[' ' for _ in range(puzzle.grid_cols)] for _ in range(puzzle.grid_rows)]
-
-        # Fill in words
-        for word in puzzle.words:
-            for i, cell in enumerate(word.cells):
-                grid[cell.x][cell.y] = word.text[i]
-
-        # Print grid
-        print("Grid visualization:")
-        print("  " + "+-" * puzzle.grid_cols + "+")
-        for row_idx, row in enumerate(grid):
-            print(f"{row_idx} |" + "|".join(row) + "|")
-        print("  " + "+-" * puzzle.grid_cols + "+")
-        print("    " + "".join(str(i) for i in range(puzzle.grid_cols)))
-        print()
-
-        print("✓ Grid visualization complete!")
-        print()
-        return True
-    except Exception as e:
-        print(f"✗ Test failed: {e}")
-        import traceback
-        traceback.print_exc()
-        return False
-
-
-def test_validation_checks():
-    """Test that validation catches errors."""
-    print("Test 5: Validation error detection")
-    print("=" * 60)
-
-    # This should work
-    try:
-        puzzle = generate_puzzle()
-        validate_puzzle(puzzle, grid_rows=6, grid_cols=8)
-        print("✓ Valid puzzle passes validation")
-    except AssertionError as e:
-        print(f"✗ Valid puzzle failed validation: {e}")
-        return False
-
-    # Test row count enforcement
-    try:
-        from wrdler.models import Word, Coord, Puzzle
-
-        # Try to create puzzle with wrong number of rows
-        words = [
-            Word("CAT", Coord(0, 0), "H"),
-            Word("DOG", Coord(1, 0), "H"),
-            Word("RAT", Coord(2, 0), "H"),
-        ]
-        bad_puzzle = Puzzle(words=words, grid_rows=6, grid_cols=8)
-
-        try:
-            validate_puzzle(bad_puzzle, grid_rows=6, grid_cols=8)
-            print("✗ Validation should have failed for 3 words (expected 6)")
-            return False
-        except AssertionError:
-            print("✓ Validation correctly rejects wrong word count")
-    except Exception as e:
-        print(f"✗ Test error: {e}")
-        return False
-
-    print()
-    return True
-
-
-def main():
-    """Run all tests."""
-    print("\n" + "=" * 60)
-    print("WRDLER PUZZLE GENERATOR TESTS")
-    print("=" * 60)
-    print()
-
-    tests = [
-        test_basic_generation,
-        test_with_seed,
-        test_target_words,
-        test_grid_visualization,
-        test_validation_checks,
-    ]
-
-    results = []
-    for test_func in tests:
-        result = test_func()
-        results.append((test_func.__name__, result))
-
-    # Summary
-    print("=" * 60)
-    print("TEST SUMMARY")
-    print("=" * 60)
-    for name, passed in results:
-        status = "✓ PASS" if passed else "✗ FAIL"
-        print(f"{status}: {name}")
-
-    total = len(results)
-    passed = sum(1 for _, p in results if p)
-    print()
-    print(f"Results: {passed}/{total} tests passed")
-    print("=" * 60)
-
-    return all(p for _, p in results)
-
-
-if __name__ == "__main__":
-    import sys
-    success = main()
-    sys.exit(0 if success else 1)

tests/test_logic.py

@@ -1,55 +0,0 @@
-import unittest
-
-from wrdler.logic import build_letter_map, reveal_cell, guess_word, is_game_over
-from wrdler.models import Coord, Word, Puzzle, GameState
-
-
-class TestLogic(unittest.TestCase):
-    def make_state(self):
-        w1 = Word("TREE", Coord(0, 0), "H")
-        w2 = Word("APPLE", Coord(2, 0), "H")
-        w3 = Word("ORANGE", Coord(4, 0), "H")
-        w4 = Word("WIND", Coord(0, 6), "V")
-        w5 = Word("MOUSE", Coord(0, 8), "V")
-        w6 = Word("PYTHON", Coord(0, 10), "V")
-        p = Puzzle([w1, w2, w3, w4, w5, w6])
-        state = GameState(
-            grid_size=12,
-            puzzle=p,
-            revealed=set(),
-            guessed=set(),
-            score=0,
-            last_action="",
-            can_guess=False,
-        )
-        return state, p
-
-    def test_reveal_and_guess_gating(self):
-        state, puzzle = self.make_state()
-        letter_map = build_letter_map(puzzle)
-        # Can't guess before reveal
-        ok, pts = guess_word(state, "TREE")
-        self.assertFalse(ok)
-        self.assertEqual(pts, 0)
-        # Reveal one cell then guess
-        reveal_cell(state, letter_map, Coord(0, 0))
-        self.assertTrue(state.can_guess)
-        ok, pts = guess_word(state, "TREE")
-        self.assertTrue(ok)
-        self.assertGreater(pts, 0)
-        self.assertIn("TREE", state.guessed)
-        self.assertFalse(state.can_guess)
-
-    def test_game_over(self):
-        state, puzzle = self.make_state()
-        letter_map = build_letter_map(puzzle)
-        # Guess all words after a reveal each time
-        for w in puzzle.words:
-            reveal_cell(state, letter_map, w.start)
-            ok, _ = guess_word(state, w.text)
-            self.assertTrue(ok)
-        self.assertTrue(is_game_over(state))
-
-
-if __name__ == "__main__":
-    unittest.main()

tests/test_models_rect.py

@@ -1,110 +0,0 @@
-# file: tests/test_models_rect.py 
-"""Unit tests for Wrdler rectangular grid support in models.py"""
-import pytest
-from wrdler.models import Coord, Word, Puzzle, GameState
-
-
-class TestCoordRectangular:
-    """Tests for Coord.in_bounds_rect() method"""
-    
-    def test_in_bounds_rect_valid_coords(self):
-        """Test that valid coordinates pass boundary check"""
-        # 6 rows x 8 cols (Wrdler grid)
-        assert Coord(0, 0).in_bounds_rect(6, 8) is True
-        assert Coord(5, 7).in_bounds_rect(6, 8) is True  # Bottom-right corner
-        assert Coord(3, 4).in_bounds_rect(6, 8) is True  # Middle
-    
-    def test_in_bounds_rect_invalid_coords(self):
-        """Test that out-of-bounds coordinates fail boundary check"""
-        # 6 rows x 8 cols
-        assert Coord(6, 0).in_bounds_rect(6, 8) is False  # Row too large
-        assert Coord(0, 8).in_bounds_rect(6, 8) is False  # Col too large
-        assert Coord(-1, 0).in_bounds_rect(6, 8) is False  # Negative row
-        assert Coord(0, -1).in_bounds_rect(6, 8) is False  # Negative col
-    
-    def test_in_bounds_backward_compatibility(self):
-        """Test that legacy in_bounds() still works for square grids"""
-        assert Coord(0, 0).in_bounds(12) is True
-        assert Coord(11, 11).in_bounds(12) is True
-        assert Coord(12, 0).in_bounds(12) is False
-
-
-class TestPuzzleRectangular:
-    """Tests for Puzzle with rectangular grid dimensions"""
-    
-    def test_puzzle_default_dimensions(self):
-        """Test that Puzzle defaults to Wrdler dimensions (6x8)"""
-        puzzle = Puzzle(words=[])
-        assert puzzle.grid_rows == 6
-        assert puzzle.grid_cols == 8
-    
-    def test_puzzle_custom_dimensions(self):
-        """Test that Puzzle can use custom dimensions"""
-        puzzle = Puzzle(words=[], grid_rows=10, grid_cols=12)
-        assert puzzle.grid_rows == 10
-        assert puzzle.grid_cols == 12
-    
-    def test_puzzle_no_radar_field(self):
-        """Test that radar field is removed from Puzzle"""
-        puzzle = Puzzle(words=[])
-        assert not hasattr(puzzle, 'radar')
-
-
-class TestGameStateRectangular:
-    """Tests for GameState with rectangular grid support"""
-    
-    def test_gamestate_default_dimensions(self):
-        """Test that GameState defaults to Wrdler dimensions (6x8)"""
-        state = GameState()
-        assert state.grid_rows == 6
-        assert state.grid_cols == 8
-    
-    def test_gamestate_free_letters_field(self):
-        """Test that free_letters field exists and is initialized"""
-        state = GameState()
-        assert hasattr(state, 'free_letters')
-        assert isinstance(state.free_letters, set)
-        assert len(state.free_letters) == 0
-    
-    def test_gamestate_free_letters_used_field(self):
-        """Test that free_letters_used field exists and is initialized to 0"""
-        state = GameState()
-        assert hasattr(state, 'free_letters_used')
-        assert state.free_letters_used == 0
-    
-    def test_gamestate_grid_size_property_square(self):
-        """Test grid_size property works for square grids"""
-        state = GameState(grid_rows=12, grid_cols=12)
-        assert state.grid_size == 12
-    
-    def test_gamestate_grid_size_property_rectangular_raises(self):
-        """Test grid_size property raises ValueError for rectangular grids"""
-        state = GameState(grid_rows=6, grid_cols=8)
-        with pytest.raises(ValueError, match="grid_size not applicable"):
-            _ = state.grid_size
-
-
-class TestWordHorizontalOnly:
-    """Tests for Word with horizontal-only placement (Wrdler requirement)"""
-    
-    def test_word_horizontal_valid(self):
-        """Test that horizontal words are created correctly"""
-        word = Word(text="WORD", start=Coord(0, 0), direction="H")
-        assert word.direction == "H"
-        assert len(word.cells) == 4
-        assert word.cells[0] == Coord(0, 0)
-        assert word.cells[3] == Coord(0, 3)
-    
-    def test_word_horizontal_fits_in_8_cols(self):
-        """Test that words fit within 8-column grid"""
-        # Max length word (8 letters) starting at column 0
-        word = Word(text="TESTWORD", start=Coord(0, 0), direction="H")
-        assert all(c.in_bounds_rect(6, 8) for c in word.cells)
-        
-        # 4-letter word starting at column 4 (last cell at column 7)
-        word = Word(text="TEST", start=Coord(0, 4), direction="H")
-        assert all(c.in_bounds_rect(6, 8) for c in word.cells)
-
-
-if __name__ == "__main__":
-    pytest.main([__file__, "-v"])

tests/test_word_distribution.py

@@ -1,38 +0,0 @@
-#!/usr/bin/env python3
-"""Quick test to verify word length distribution in generated puzzles."""
-
-from wrdler.generator import generate_puzzle
-from wrdler.word_loader import load_word_list
-
-def test_word_distribution():
-    """Test that puzzles have 2 four-letter, 2 five-letter, and 2 six-letter words."""
-    print("Testing word distribution in generated puzzles...")
-
-    # Load word list
-    words_by_len = load_word_list()
-    print(f"Loaded words: {len(words_by_len[4])} 4-letter, {len(words_by_len[5])} 5-letter, {len(words_by_len[6])} 6-letter")
-
-    # Generate 5 test puzzles
-    for i in range(5):
-        puzzle = generate_puzzle(grid_rows=6, grid_cols=8, words_by_len=words_by_len)
-
-        # Count word lengths
-        length_counts = {4: 0, 5: 0, 6: 0}
-        for word in puzzle.words:
-            length = len(word.text)
-            if length in length_counts:
-                length_counts[length] += 1
-
-        # Verify distribution
-        assert length_counts[4] == 2, f"Puzzle {i+1}: Expected 2 four-letter words, got {length_counts[4]}"
-        assert length_counts[5] == 2, f"Puzzle {i+1}: Expected 2 five-letter words, got {length_counts[5]}"
-        assert length_counts[6] == 2, f"Puzzle {i+1}: Expected 2 six-letter words, got {length_counts[6]}"
-
-        # Print puzzle info
-        words_str = ", ".join([f"{w.text}({len(w.text)})" for w in puzzle.words])
-        print(f"✓ Puzzle {i+1}: {words_str}")
-
-    print("\n✅ All tests passed! Word distribution is correct.")
-
-if __name__ == "__main__":
-    test_word_distribution()

tests/test_word_file_validation.py

@@ -1,67 +0,0 @@
-"""
-Test validation of word files for MIN_REQUIRED threshold compliance.
-"""
-
-import os
-import tempfile
-import shutil
-from wrdler.word_loader_ai import _save_ai_words_to_file
-from wrdler.word_loader import MIN_REQUIRED
-
-
-def test_save_ai_words_validates_min_required():
-    """Test that _save_ai_words_to_file returns insufficiency info."""
-    # Create a temporary directory for test files
-    test_dir = tempfile.mkdtemp()
-    
-    try:
-        # Mock the words directory to point to our temp dir
-        import wrdler.word_loader_ai as wl_ai
-        original_dirname = wl_ai.os.path.dirname
-        
-        def mock_dirname(path):
-            if "word_loader_ai.py" in path:
-                return test_dir
-            return original_dirname(path)
-        
-        wl_ai.os.path.dirname = mock_dirname
-        
-        # Test case 1: Insufficient words (should return non-empty dict)
-        insufficient_words = [
-            "COOK", "BAKE", "HEAT",  # 3 x 4-letter (need 25)
-            "ROAST", "GRILL", "STEAM",  # 3 x 5-letter (need 25)
-            "SIMMER", "BRAISE",  # 2 x 6-letter (need 25)
-        ]
-        
-        filename, insufficient = _save_ai_words_to_file("test_topic", insufficient_words)
-        
-        assert filename == "test_topic.txt", f"Expected 'test_topic.txt', got '{filename}'"
-        assert len(insufficient) > 0, "Expected insufficient_lengths to be non-empty"
-        assert 4 in insufficient, "Expected 4-letter words to be insufficient"
-        assert 5 in insufficient, "Expected 5-letter words to be insufficient"
-        assert 6 in insufficient, "Expected 6-letter words to be insufficient"
-        
-        # Test case 2: Sufficient words (should return empty dict)
-        sufficient_words = []
-        for length in [4, 5, 6]:
-            for i in range(MIN_REQUIRED):
-                # Generate unique words of the required length
-                word = chr(65 + (i % 26)) * length + str(i).zfill(length - 1)
-                sufficient_words.append(word[:length].upper())
-        
-        filename2, insufficient2 = _save_ai_words_to_file("test_sufficient", sufficient_words)
-        
-        assert filename2 == "test_sufficient.txt", f"Expected 'test_sufficient.txt', got '{filename2}'"
-        assert len(insufficient2) == 0, f"Expected empty insufficient_lengths, got {insufficient2}"
-        
-        print("? All validation tests passed!")
-        
-    finally:
-        # Restore original dirname
-        wl_ai.os.path.dirname = original_dirname
-        # Clean up temp directory
-        shutil.rmtree(test_dir, ignore_errors=True)
-
-
-if __name__ == "__main__":
-    test_save_ai_words_validates_min_required()

wrdler/__init__.py

@@ -8,5 +8,5 @@ Key differences from BattleWords:
 - 2 free letter guesses at game start
 """
 
-__version__ = "0.1.4"
+__version__ = "0.1.5"
 __all__ = ["models", "generator", "logic", "ui", "word_loader"]

wrdler/audio.py

@@ -1,47 +1,56 @@
+"""
+Streamlit-specific audio utilities for Wrdler.
+
+This module provides audio playback functionality for the Streamlit UI.
+Uses base64 encoding for audio files since Streamlit doesn't serve arbitrary directories.
+"""
+
 import os
 from typing import Optional
 import streamlit as st
 
-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, absolute_path) for .mp3 files in assets/audio/music."""
-    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)
-            # Use the filename without extension as the display name
-            name = os.path.splitext(fname)[0]
-            tracks.append((name, path))
-    return tracks
+# Import shared core functions
+from .audio_core import (
+    get_music_dir as _get_music_dir,
+    get_effects_dir as _get_effects_dir,
+    get_audio_tracks,
+    get_sound_effect_files,
+    get_background_music_path,
+    clamp_volume
+)
+
 
 @st.cache_data(show_spinner=False)
 def _load_audio_data_url(path: str) -> str:
-    """Return a data: URL for the given audio file so the browser can play it."""
+    """
+    Convert audio file to data URL for browser playback.
+    
+    Streamlit requires base64 encoding since it doesn't serve arbitrary directories.
+    
+    Args:
+        path: Absolute path to audio file
+    
+    Returns:
+        Base64-encoded data URL
+    """
     import base64, mimetypes
     mime, _ = mimetypes.guess_type(path)
     if not mime:
-        # Default to mp3 to avoid blocked playback if unknown
         mime = "audio/mpeg"
     with open(path, "rb") as fp:
         encoded = base64.b64encode(fp.read()).decode("ascii")
     return f"data:{mime};base64,{encoded}"
 
+
 def _mount_background_audio(enabled: bool, src_data_url: Optional[str], volume: float, loop: bool = True) -> None:
-    """Create/update a single hidden <audio> element in the top page and play/pause it.
+    """
+    Create/update a single hidden <audio> element in the page.
 
     Args:
-        enabled: Whether the background audio should be active.
-        src_data_url: data: URL for the audio source.
-        volume: 0.0–1.0 volume level.
-        loop: Whether the audio should loop (default True).
+        enabled: Whether the background audio should be active
+        src_data_url: Base64 data URL for the audio source
+        volume: Volume level (0.0 to 1.0)
+        loop: Whether the audio should loop (default True)
     """
     from streamlit.components.v1 import html as _html
 
@@ -60,11 +69,9 @@ def _mount_background_audio(enabled: bool, src_data_url: Optional[str], volume:
         )
         return
 
-    # Clamp volume
-    vol = max(0.0, min(1.0, float(volume)))
+    vol = clamp_volume(volume)
     should_loop = "true" if loop else "false"
 
-    # Inject or update a single persistent audio element and make sure it starts after interaction if autoplay is blocked
     _html(
         f"""
         <script>
@@ -78,7 +85,6 @@ def _mount_background_audio(enabled: bool, src_data_url: Optional[str], volume:
             doc.body.appendChild(audio);
           }}
 
-          // Ensure loop is explicitly set every time, even if element already exists
           const shouldLoop = {should_loop};
           audio.loop = shouldLoop;
           if (shouldLoop) {{
@@ -98,14 +104,11 @@ def _mount_background_audio(enabled: bool, src_data_url: Optional[str], volume:
 
           const tryPlay = () => {{
             const p = audio.play();
-            if (p && p.catch) {{ p.catch(() => {{ /* ignore autoplay block until user gesture */ }}); }}
+            if (p && p.catch) {{ p.catch(() => {{}}); }}
           }};
           tryPlay();
 
-          const unlock = () => {{
-            tryPlay();
-          }};
-          // Add once-only listeners to resume playback after first user interaction
+          const unlock = () => {{ tryPlay(); }};
           doc.addEventListener('pointerdown', unlock, {{ once: true }});
           doc.addEventListener('keydown', unlock, {{ once: true }});
           doc.addEventListener('touchstart', unlock, {{ once: true }});
@@ -115,6 +118,7 @@ def _mount_background_audio(enabled: bool, src_data_url: Optional[str], volume:
         height=0,
     )
 
+
 def _inject_audio_control_sync():
     """Inject JS to sync volume and enable/disable state immediately."""
     from streamlit.components.v1 import html as _html
@@ -125,14 +129,12 @@ def _inject_audio_control_sync():
           const doc = window.parent?.document || document;
           const audio = doc.getElementById('bw-bg-audio');
           if (!audio) return;
-          // Get values from Streamlit DOM
           const volInput = doc.querySelector('input[type="range"][aria-label="Volume"]');
           const enableInput = doc.querySelector('input[type="checkbox"][aria-label="Enable music"]');
           if (volInput) {
             volInput.addEventListener('input', function(){
               audio.volume = parseFloat(this.value)/100;
             });
-            // Set initial volume
             audio.volume = parseFloat(volInput.value)/100;
           }
           if (enableInput) {
@@ -145,7 +147,6 @@ def _inject_audio_control_sync():
                 audio.pause();
               }
             });
-            // Set initial mute state
             if (enableInput.checked) {
               audio.muted = false;
               audio.play().catch(()=>{});
@@ -160,43 +161,10 @@ def _inject_audio_control_sync():
         height=0,
     )
 
-# Sound effects functionality
-def get_sound_effect_files() -> dict[str, str]:
-    """
-    Return dictionary of sound effect name -> absolute path.
-    Prefers .mp3 files; falls back to .wav if no .mp3 is found.
-    """
-    audio_dir = _get_effects_dir()
-    if not os.path.isdir(audio_dir):
-        return {}
-
-    effect_names = [
-        "correct_guess",
-        "incorrect_guess",
-        "hit",
-        "miss",
-        "congratulations",
-    ]
-
-    def _find_effect_file(base: str) -> Optional[str]:
-        # Prefer mp3, then wav for backward compatibility
-        for ext in (".mp3", ".wav"):
-            path = os.path.join(audio_dir, f"{base}{ext}")
-            if os.path.exists(path):
-                return path
-        return None
-
-    result: dict[str, str] = {}
-    for name in effect_names:
-        path = _find_effect_file(name)
-        if path:
-            result[name] = path
-
-    return result
 
 def play_sound_effect(effect_name: str, volume: float = 0.5) -> None:
     """
-    Play a sound effect by name.
+    Play a sound effect by name (Streamlit implementation).
 
     Args:
         effect_name: One of 'correct_guess', 'incorrect_guess', 'hit', 'miss', 'congratulations'
@@ -212,17 +180,14 @@ def play_sound_effect(effect_name: str, volume: float = 0.5) -> None:
         pass
 
     sound_files = get_sound_effect_files()
-
     if effect_name not in sound_files:
-        return  # Sound file doesn't exist, silently skip
+        return
 
     sound_path = sound_files[effect_name]
     sound_data_url = _load_audio_data_url(sound_path)
 
-    # Clamp volume
-    vol = max(0.0, min(1.0, float(volume)))
+    vol = clamp_volume(volume)
 
-    # Play sound effect using a unique audio element
     _html(
         f"""
         <script>
@@ -234,7 +199,6 @@ def play_sound_effect(effect_name: str, volume: float = 0.5) -> None:
           audio.style.display = 'none';
           doc.body.appendChild(audio);
 
-          // Play and remove after playback
           audio.play().catch(e => console.error('Sound effect play error:', e));
           audio.addEventListener('ended', () => {{
             doc.body.removeChild(audio);

wrdler/audio_core.py

@@ -0,0 +1,175 @@
+"""
+Core audio utilities for Wrdler - Framework-agnostic.
+
+This module provides shared audio functionality that works with both
+Streamlit and Gradio interfaces. Framework-specific implementations
+should import these functions and add their own rendering logic.
+"""
+
+import os
+from typing import Dict, List, Optional, Tuple
+
+
+def get_music_dir() -> str:
+    """Get absolute path to music directory."""
+    return os.path.join(os.path.dirname(__file__), "assets", "audio", "music")
+
+
+def get_effects_dir() -> str:
+    """Get absolute path to effects directory."""
+    return os.path.join(os.path.dirname(__file__), "assets", "audio", "effects")
+
+
+def get_audio_tracks() -> List[Tuple[str, str]]:
+    """
+    Get available music tracks.
+
+    Returns:
+        List of (track_name, absolute_path) tuples for .mp3 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]:
+    """
+    Get available sound effect files.
+
+    Returns:
+        Dictionary of effect_name -> absolute_path
+        Prefers .mp3 files, falls back to .wav
+    """
+    audio_dir = get_effects_dir()
+    if not os.path.isdir(audio_dir):
+        return {}
+
+    effect_names = [
+        "correct_guess",
+        "incorrect_guess",
+        "hit",
+        "miss",
+        "congratulations",
+    ]
+
+    def _find_effect_file(base: str) -> Optional[str]:
+        """Find effect file, preferring .mp3 over .wav."""
+        for ext in (".mp3", ".wav"):
+            path = os.path.join(audio_dir, f"{base}{ext}")
+            if os.path.exists(path):
+                return path
+        return None
+
+    result: Dict[str, str] = {}
+    for name in effect_names:
+        path = _find_effect_file(name)
+        if path:
+            result[name] = path
+
+    return result
+
+
+def get_background_music_path(prefer_name: str = "background") -> Optional[str]:
+    """
+    Get path to background music file.
+
+    Args:
+        prefer_name: Preferred track name (default: "background")
+
+    Returns:
+        Absolute path to music file, or None if no tracks available
+    """
+    try:
+        tracks = get_audio_tracks()
+        print(f"[Audio Debug] get_audio_tracks() returned: {tracks}")
+        
+        if not tracks:
+            print("[Audio Debug] No audio tracks found")
+            return None
+
+        # Try to find preferred track
+        for name, path in tracks:
+            if name.lower() == prefer_name.lower():
+                print(f"[Audio Debug] Found preferred track '{prefer_name}' at: {path}")
+                # Verify it's a file, not a directory
+                if not os.path.isfile(path):
+                    print(f"[Audio Debug] Path is not a file: {path}")
+                    continue
+                return path
+
+        # Fall back to first track
+        fallback_name, fallback_path = tracks[0]
+        print(f"[Audio Debug] Using fallback track '{fallback_name}' at: {fallback_path}")
+        
+        # Verify it's a file, not a directory
+        if not os.path.isfile(fallback_path):
+            print(f"[Audio Debug] Fallback path is not a file: {fallback_path}")
+            return None
+            
+        return fallback_path
+    except Exception as e:
+        print(f"[Audio Debug] Error in get_background_music_path: {e}")
+        import traceback
+        traceback.print_exc()
+        return None
+
+
+def clamp_volume(volume: float) -> float:
+    """
+    Clamp volume to valid range [0.0, 1.0].
+
+    Args:
+        volume: Volume value to clamp
+
+    Returns:
+        Clamped volume in range [0.0, 1.0]
+    """
+    return max(0.0, min(1.0, float(volume)))
+
+
+def get_audio_file_url(file_path: str) -> str:
+    """
+    Convert local file path to Gradio-served URL.
+    
+    Gradio's file serving endpoint is /gradio_api/file= with paths 
+    relative to directories in allowed_paths.
+    
+    Args:
+        file_path: Absolute path to audio file
+    
+    Returns:
+        URL for Gradio's file serving endpoint with full relative path
+    """
+    import os
+    
+    # Get the project root (parent of wrdler package)
+    project_root = os.path.dirname(os.path.dirname(__file__))
+    
+    # Get path relative to project root (website root)
+    try:
+        rel_path = os.path.relpath(file_path, project_root)
+    except ValueError:
+        # Fallback for Windows different drives
+        rel_path = os.path.basename(file_path)
+    
+    # Normalize to forward slashes for URLs
+    url_path = rel_path.replace(os.sep, '/')
+    
+    # Gradio's file serving endpoint
+    url = f"/gradio_api/file={url_path}"
+    
+    print(f"[Audio URL] File: {file_path}")
+    print(f"[Audio URL] Project root: {project_root}")
+    print(f"[Audio URL] Relative path: {url_path}")
+    print(f"[Audio URL] Final URL: {url}")
+    
+    return url

wrdler/gradio_ui.py

@@ -46,6 +46,30 @@ GRID_ROWS = 6
 GRID_COLS = 8
 MAX_FREE_LETTERS = 2
 
+# ---------------------------------------------------------------------------
+# Register Static Paths for Audio Files (Gradio file serving)
+# ---------------------------------------------------------------------------
+
+# Register audio directory at module level so Gradio can serve files directly
+_AUDIO_DIR = os.path.join(os.path.dirname(__file__), "assets", "audio")
+_STATIC_SERVE_ENABLED = False
+if os.path.isdir(_AUDIO_DIR):
+    try:
+        gr.set_static_paths(paths=[_AUDIO_DIR])
+        _STATIC_SERVE_ENABLED = True
+    except (AttributeError, Exception):
+        # Graceful fallback if set_static_paths not available or fails
+        _STATIC_SERVE_ENABLED = False
+        pass
+
+# Register static directory for favicon and other static assets
+_STATIC_DIR = os.path.join(os.path.dirname(os.path.dirname(__file__)), "static")
+if os.path.isdir(_STATIC_DIR):
+    try:
+        gr.set_static_paths(paths=[_STATIC_DIR])
+    except (AttributeError, Exception):
+        pass
+
 # ---------------------------------------------------------------------------
 # Settings Loading
 # ---------------------------------------------------------------------------
@@ -59,9 +83,9 @@ def load_settings() -> Dict[str, Any]:
         "enable_free_letters": True,
         "show_challenge_links": True,
         "sound_effects_enabled": True,
-        "sound_effects_volume": 50,
+        "sound_effects_volume": 10,  # Changed from 50 to 10
         "music_enabled": False,
-        "music_volume": 30,
+        "music_volume": 10,  # Changed from 30 to 10
         "default_wordlist": "classic.txt",
         "default_game_mode": "classic"
     }
@@ -105,48 +129,31 @@ 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
+# Import shared core functions
+from .audio_core import (
+    get_music_dir as _get_music_dir,
+    get_effects_dir as _get_effects_dir,
+    get_audio_tracks,
+    get_sound_effect_files,
+    get_background_music_path,
+    get_audio_file_url,
+    clamp_volume
+)
 
 
 @lru_cache(maxsize=32)
 def load_audio_data_url(path: str) -> str:
-    """Convert audio file to data URL for browser playback."""
+    """
+    Convert audio file to data URL for browser playback.
+    
+    Fallback method using base64 encoding. Used when direct file serving fails.
+    
+    Args:
+        path: Absolute path to audio file
+    
+    Returns:
+        Base64-encoded data URL
+    """
     mime, _ = mimetypes.guess_type(path)
     if not mime:
         mime = "audio/mpeg"
@@ -158,102 +165,72 @@ def load_audio_data_url(path: str) -> str:
         return ""
 
 
-def render_background_music_html(enabled: bool, volume: float) -> str:
-    """Generate HTML to control background music player.
+def _resolve_audio_src(path: Optional[str]) -> str:
+    """Resolve audio source to a playable URL using Gradio's file serving.
     
-    Creates or updates a persistent audio element in the parent document.
-    The music will loop continuously when enabled.
+    Uses relative paths from the project root that work both locally 
+    and on Hugging Face Spaces.
     
     Args:
-        enabled: Whether background music should play
-        volume: Volume level (0.0 to 1.0)
+        path: Absolute path to audio file
     
     Returns:
-        HTML/JavaScript to inject into the page
+        Gradio /file= URL with relative path
     """
-    # Get the first available music track (background.mp3 preferred)
-    tracks = get_audio_tracks()
-    if not tracks:
+    if not path:
         return ""
     
-    # Prefer background.mp3, otherwise use first track
-    music_path = None
-    for name, path in tracks:
-        if name.lower() == "background":
-            music_path = path
-            break
-    if not music_path:
-        music_path = tracks[0][1]
-    
-    data_url = load_audio_data_url(music_path)
-    if not data_url:
-        return ""
-    
-    vol = max(0.0, min(1.0, float(volume)))
-    
-    if enabled:
-        return f'''
-<script>
-(function(){{
-    const doc = window.parent?.document || document;
-    let audio = doc.getElementById('wrdler-bg-music');
-    
-    if (!audio) {{
-        audio = doc.createElement('audio');
-        audio.id = 'wrdler-bg-music';
-        audio.loop = true;
-        audio.style.display = 'none';
-        doc.body.appendChild(audio);
-    }}
-    
-    const newSrc = "{data_url}";
-    if (audio.src !== newSrc) {{
-        audio.src = newSrc;
-    }}
+    # Always use Gradio's file serving endpoint
+    # This works both locally and on Hugging Face
+    try:
+        url = get_audio_file_url(path)
+        if url:
+            return url
+    except Exception:
+        pass
     
-    audio.volume = {vol:.3f};
-    audio.muted = false;
+    # Fallback to base64 only if file URL generation fails
+    return load_audio_data_url(path)
+
+
+def render_background_music_html(enabled: bool, volume: float) -> str:
+    """
+    Generate HTML for background music player (Gradio implementation).
     
-    const tryPlay = () => {{
-        const p = audio.play();
-        if (p && p.catch) {{
-            p.catch(() => {{
-                console.log('Music autoplay blocked - waiting for user interaction');
-                console.log('Click anywhere on the page to start music');
-            }});
-        }}
-    }};
+    Returns just the audio element HTML with autoplay attribute.
+    Note: Autoplay may be blocked by browser until first user interaction.
     
-    tryPlay();
+    Args:
+        enabled: Whether background music should play
+        volume: Volume level (0.0 to 1.0)
     
-    // Add user interaction listeners to unlock autoplay
-    const unlock = () => {{
-        tryPlay();
-        doc.removeEventListener('pointerdown', unlock);
-        doc.removeEventListener('keydown', unlock);
-        doc.removeEventListener('touchstart', unlock);
-    }};
+    Returns:
+        HTML string with audio element
+    """
+    if not enabled:
+        return "<div style='display:none;' id='music-player-container'></div>"
     
-    doc.addEventListener('pointerdown', unlock, {{ once: true }});
-    doc.addEventListener('keydown', unlock, {{ once: true }});
-    doc.addEventListener('touchstart', unlock, {{ once: true }});
-}})();
-</script>
-'''
-    else:
-        # Pause music when disabled
-        return '''
-<script>
-(function(){
-    const doc = window.parent?.document || document;
-    const audio = doc.getElementById('wrdler-bg-music');
-    if (audio) {
-        audio.pause();
-        audio.muted = true;
-    }
-})();
-</script>
-'''
+    try:
+        music_path = get_background_music_path("background")
+        if not music_path or not os.path.exists(music_path) or not os.path.isfile(music_path):
+            return "<div style='display:none;' id='music-player-container'></div>"
+        
+        audio_url = get_audio_file_url(music_path)
+        vol = clamp_volume(volume)
+        
+        # Simple HTML5 audio with autoplay
+        # Volume will be set by browser default initially, updated on user interaction
+        html = f"""
+        <div id='music-player-container' style='display:none;'>
+            <audio id='bg-music-player' autoplay loop preload='auto' volume='{vol:.2f}'>
+                <source src='{audio_url}' type='audio/mpeg'>
+            </audio>
+        </div>
+        """
+        return html
+    except Exception as e:
+        print(f"[Audio] Error in render_background_music_html: {e}")
+        return "<div style='display:none;' id='music-player-container'></div>"
 
 
 def render_audio_player_html(
@@ -261,10 +238,10 @@ def render_audio_player_html(
     volume: float = 0.5,
     enabled: bool = True
 ) -> str:
-    """Generate HTML to play a sound effect.
+    """
+    Generate HTML for sound effect playback (Gradio implementation).
     
-    Creates a temporary audio element that plays once and removes itself.
-    Sound effects are independent of background music.
+    Returns simple HTML5 audio element with autoplay.
     
     Args:
         effect_name: Name of the sound effect to play
@@ -272,55 +249,39 @@ def render_audio_player_html(
         enabled: Whether sound effects are enabled
     
     Returns:
-        HTML/JavaScript to inject into the page
+        HTML string with audio element
     """
     if not enabled or not effect_name:
-        return ""
-
-    sound_files = get_sound_effect_files()
-    if effect_name not in sound_files:
-        return ""
+        return "<div style='display:none;'></div>"
 
-    data_url = load_audio_data_url(sound_files[effect_name])
-    if not data_url:
-        return ""
+    try:
+        sound_files = get_sound_effect_files()
+        if effect_name not in sound_files:
+            return "<div style='display:none;'></div>"
 
-    vol = max(0.0, min(1.0, float(volume)))
-
-    return f'''
-<script>
-(function(){{
-    const doc = window.parent?.document || document;
-    const audio = doc.createElement('audio');
-    audio.src = "{data_url}";
-    audio.volume = {vol:.3f};
-    audio.style.display = 'none';
-    doc.body.appendChild(audio);
-    
-    // Play and remove after playback
-    const playPromise = audio.play();
-    if (playPromise) {{
-        playPromise.catch(e => {{
-            console.log('Sound effect play blocked:', e.message);
-            doc.body.removeChild(audio);
-        }});
-    }}
-    
-    audio.addEventListener('ended', () => {{
-        if (audio.parentNode) {{
-            doc.body.removeChild(audio);
-        }}
-    }});
-    
-    // Fallback cleanup after 10 seconds
-    setTimeout(() => {{
-        if (audio.parentNode) {{
-            doc.body.removeChild(audio);
-        }}
-    }}, 10000);
-}})();
-</script>
-'''
+        sound_path = sound_files[effect_name]
+        if not os.path.exists(sound_path) or not os.path.isfile(sound_path):
+            return "<div style='display:none;'></div>"
+        
+        audio_url = get_audio_file_url(sound_path)
+        vol = clamp_volume(volume)
+        
+        # Use timestamp to ensure unique ID
+        import time
+        audio_id = f"sfx-{int(time.time() * 1000)}"
+        
+        # Simple autoplay audio (will play after user interaction)
+        html = f"""
+        <div style='display:none;'>
+            <audio id='{audio_id}' autoplay preload='auto' volume='{vol:.2f}'>
+                <source src='{audio_url}' type='audio/mpeg'>
+            </audio>
+        </div>
+        """
+        return html
+    except Exception as e:
+        print(f"[Audio] Error in render_audio_player_html: {e}")
+        return "<div style='display:none;'></div>"
 
 
 # ---------------------------------------------------------------------------
@@ -789,7 +750,7 @@ def render_score_panel_html(state: Dict[str, Any]) -> str:
       {incorrect_html}
       <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 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>
@@ -802,7 +763,7 @@ 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 ""
+        return "<div style='display:none;'></div>"
 
     enabled = state.get("sound_effects_enabled", True)
     volume = state.get("sound_effects_volume", 50) / 100.0
@@ -831,7 +792,7 @@ def render_challenge_leaderboard_html(state: Dict[str, Any]) -> str:
     ]
 
     # Sort by score desc, then time asc
-    sorted_lb = sorted(leaderboard, key=lambda x: (-x.get("score", 0), x.get("time", 9999)))
+    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
@@ -861,12 +822,15 @@ def render_game_over_html(state: Dict[str, Any]) -> str:
 
     # 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}"
+        try:
+            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}"
+        except Exception:
+            time_str = "--:--"
     else:
         time_str = "--:--"
 
@@ -958,7 +922,7 @@ def get_letter_button_updates(state: Dict[str, Any]) -> List[gr.Button]:
 
 
 def build_ui_outputs(state: Dict[str, Any], audio_html: str = "") -> tuple:
-    """Build the complete UI output tuple for all handlers.
+    """Build the complete UI output for all handlers.
 
     Returns: (48 grid buttons, 26 letter buttons, score_panel, status_msg, audio, game_over, free_letter_status, free_letter_row, game_over_modal, share_section, state)
     """
@@ -1189,7 +1153,7 @@ def handle_audio_settings_change(
     music_volume: int,
     state: Dict[str, Any]
 ) -> Tuple[Dict[str, Any], str, str]:
-    """Handle audio settings changes and return updated state + music HTML + preview audio.
+    """Handle audio settings changes and return updated state + music HTML + preview audio HTML.
     
     Returns:
         Tuple of (updated_state, music_html, preview_audio_html)
@@ -1203,13 +1167,13 @@ def handle_audio_settings_change(
     new_state["music_enabled"] = music_enabled
     new_state["music_volume"] = music_volume
     
-    # Generate music control HTML (updates background music volume)
+    # Generate music HTML (updates background music volume)
     music_html = render_background_music_html(music_enabled, music_volume / 100.0)
     
     # No preview audio by default
-    preview_audio = ""
+    preview_audio_html = "<div style='display:none;'></div>"
     
-    return new_state, music_html, preview_audio
+    return new_state, music_html, preview_audio_html
 
 
 def handle_sfx_volume_change(
@@ -1233,15 +1197,15 @@ def handle_sfx_volume_change(
     new_state["music_enabled"] = music_enabled
     new_state["music_volume"] = music_volume
     
-    # Generate music control HTML
+    # Generate music HTML
     music_html = render_background_music_html(music_enabled, music_volume / 100.0)
     
     # Play preview sound effect at new volume level (only if enabled)
-    preview_audio = ""
+    preview_audio_html = "<div style='display:none;'></div>"
     if sfx_enabled:
-        preview_audio = render_audio_player_html("hit", sfx_volume / 100.0, True)
+        preview_audio_html = render_audio_player_html("hit", sfx_volume / 100.0, True)
     
-    return new_state, music_html, preview_audio
+    return new_state, music_html, preview_audio_html
 
 
 def handle_music_volume_change(
@@ -1265,13 +1229,14 @@ def handle_music_volume_change(
     new_state["music_enabled"] = music_enabled
     new_state["music_volume"] = music_volume
     
-    # Generate music control HTML (this updates the volume in real-time)
+    # Generate music HTML (this updates the volume in real-time)
     music_html = render_background_music_html(music_enabled, music_volume / 100.0)
     
     # No preview audio by default
-    preview_audio = ""
+    preview_audio_html = "<div style='display:none;'></div>"
     
-    return new_state, music_html, preview_audio
+    return new_state, music_html, preview_audio_html
+
 
 def handle_show_incorrect_change(show_incorrect, wordlist, ai_topic, game_mode, sfx_en, sfx_vol, music_en, music_vol, enable_fl, show_chal, state):
             state = ensure_state(state)
@@ -1473,9 +1438,11 @@ def create_app() -> gr.Blocks:
                         sfx_volume = gr.Slider(
                             minimum=0,
                             maximum=100,
-                            value=APP_SETTINGS.get("sound_effects_volume", 50),
+                            value=10,  # Changed from 50 to 10
                             step=1,
-                            label="Sound Effects Volume"
+                            elem_id="sfx-volume-slider",
+                            label="Sound Effects Volume",
+                            key="sfx-volume-slider"
                         )
                         music_enabled = gr.Checkbox(
                             value=APP_SETTINGS.get("music_enabled", False),
@@ -1484,16 +1451,24 @@ def create_app() -> gr.Blocks:
                         music_volume = gr.Slider(
                             minimum=0,
                             maximum=100,
-                            value=APP_SETTINGS.get("music_volume", 30),
+                            value=10,  # Changed from 30 to 10
                             step=1,
-                            label="Music Volume"
+                            elem_id="music-volume-slider",
+                            label="Music Volume",
+                            key="music-volume-slider"
                         )
 
-        # Audio player for sound effects (hidden via CSS but still executes)
-        audio_player_html = gr.HTML(value="", elem_id="audio-player", elem_classes=["hidden-audio"])
+        # Audio players using HTML components for better compatibility
+        audio_player = gr.HTML(
+            value="<div style='display:none;'></div>",
+            elem_id="audio-player"
+        )
         
-        # Background music player (hidden but persistent)
-        music_player_html = gr.HTML(value="", elem_id="music-player", elem_classes=["hidden-audio"])
+        # Background music player using HTML component
+        music_player = gr.HTML(
+            value="<div style='display:none;'></div>",
+            elem_id="music-player"
+        )
 
         # Timer for updating elapsed time (ticks every second)
         game_timer = gr.Timer(value=1, active=True)
@@ -1520,9 +1495,9 @@ def create_app() -> gr.Blocks:
                 share_status = gr.Markdown(value="", elem_id="share-status")
                 share_url_display = gr.Textbox(
                     label="Share URL (click to copy)",
-                    value="",
+                    value="//aiprod.wrh.r.appspot.com/file=hf_space_challenge_16bee9a3-65a7-4b5a-8060-5052458808d0",
                     interactive=False,
-                    visible=False,
+                    visible=True,
                     elem_id="share-url-display"
                 )
 
@@ -1535,7 +1510,7 @@ def create_app() -> gr.Blocks:
             *letter_buttons,
             score_panel_html,
             status_msg,
-            audio_player_html,
+            audio_player,  # Changed from audio_player_html
             game_over_html,
             free_letter_status,
             free_letter_row,
@@ -1551,7 +1526,7 @@ def create_app() -> gr.Blocks:
             score_panel_html,
             status_msg,
             guess_input,  # Will be cleared
-            audio_player_html,
+            audio_player,  # Changed from audio_player_html
             game_over_html,
             free_letter_status,
             free_letter_row,
@@ -1758,22 +1733,22 @@ def create_app() -> gr.Blocks:
         sfx_enabled.change(
             fn=handle_audio_settings_change,            
             inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
-            outputs=[game_state, music_player_html, audio_player_html]
+            outputs=[game_state, music_player, audio_player]
         )
         sfx_volume.change(
             fn=handle_sfx_volume_change,
             inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
-            outputs=[game_state, music_player_html, audio_player_html]
+            outputs=[game_state, music_player, audio_player]
         )
         music_enabled.change(
             fn=handle_audio_settings_change,
             inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
-            outputs=[game_state, music_player_html, audio_player_html]
+            outputs=[game_state, music_player, audio_player]
         )
         music_volume.change(
             fn=handle_music_volume_change,
             inputs=[sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
-            outputs=[game_state, music_player_html, audio_player_html]
+            outputs=[game_state, music_player, audio_player]
         )
 
         # Show incorrect guesses toggle handler - starts new game
@@ -1833,7 +1808,7 @@ def create_app() -> gr.Blocks:
             new_state["show_challenge_links"] = enabled
             if not enable_fl:
                 new_state["last_action"] = "Free letters disabled. Click grid cells to reveal letters!"
-            return build_ui_outputs(new_state)
+            return build_uioutputs(new_state)
 
         show_challenge_links.change(
             fn=handle_show_challenge_links_change,
@@ -1894,7 +1869,90 @@ def create_app() -> gr.Blocks:
         demo.load(
             fn=initialize_ui,
             inputs=[game_state],
-            outputs=[*common_outputs, music_player_html]
+            outputs=[*common_outputs, music_player]
         )
 
-    return demo
+    return demo
+
+def handle_share_challenge(username: str, state: Dict[str, Any]) -> Tuple[str, Optional[str], Dict[str, Any]]:
+    """Create or reuse a shareable challenge link for the finished game.
+
+    Args:
+        username: Player provided name (optional / may be empty)
+        state: Current game state dictionary
+
+    Returns:
+        (status_message, share_url or None, updated_state)
+    """
+    state = ensure_state(state)
+
+    # Must be game over to share
+    if not state.get("game_over"):
+        return ("Finish the game before generating a share link.", None, state)
+
+    # If already generated, just return existing
+    existing_url = state.get("share_url")
+    if existing_url:
+        return ("Share link already generated.", existing_url, state)
+
+    # Normalize username
+    name = (username or "Anonymous").strip()
+    if not name:
+        name = "Anonymous"
+
+    # Compute elapsed time in seconds
+    try:
+        start_time = datetime.fromisoformat(state.get("start_time")) if state.get("start_time") else None
+        end_time = datetime.fromisoformat(state.get("end_time")) if state.get("end_time") else datetime.now()
+        if start_time and end_time:
+            time_seconds = int((end_time - start_time).total_seconds())
+        else:
+            time_seconds = 0
+    except Exception:
+        time_seconds = 0
+
+    # Extract word list used in this puzzle
+    word_list = [w[0] for w in state.get("puzzle_words", [])]
+
+    # Prepare parameters
+    score = state.get("score", 0)
+    game_mode = state.get("game_mode", "classic")
+    wordlist_source = state.get("wordlist")
+    show_incorrect = state.get("show_incorrect_guesses", True)
+    enable_free = state.get("enable_free_letters", True)
+    game_title = APP_SETTINGS.get("game_title")
+
+    try:
+        challenge_id, full_url, sid = save_game_to_hf(
+            word_list=word_list,
+            username=name,
+            score=score,
+            time_seconds=time_seconds,
+            game_mode=game_mode,
+            wordlist_source=wordlist_source,
+            game_title=game_title,
+            show_incorrect_guesses=show_incorrect,
+            enable_free_letters=enable_free
+        )
+        if sid:
+            share_url = get_shareable_url(sid)
+            # Create a deep copy to ensure Gradio notices state change
+            new_state = copy.deepcopy(state)
+            new_state["share_url"] = share_url
+            new_state["challenge_sid"] = sid
+            new_state["challenge_mode"] = True
+            # Initialize or extend leaderboard
+            lb_entry = {"username": name, "score": score, "time": time_seconds}
+            if not new_state.get("challenge_leaderboard"):
+                new_state["challenge_leaderboard"] = [lb_entry]
+            else:
+                # Avoid duplicate user entries with same uid/score/time
+                exists = any(e.get("username") == name and e.get("score") == score and e.get("time") == time_seconds for e in new_state["challenge_leaderboard"])
+                if not exists:
+                    new_state["challenge_leaderboard"].append(lb_entry)
+            status = f"Challenge created! Share with friends: {share_url}";
+            return (status, share_url, new_state)
+        else:
+            return ("Challenge saved but short link creation failed.", full_url, state)
+    except Exception as e:
+        return (f"Failed to create share link: {e}", None, state)

wrdler/word_loader_ai.py

@@ -793,6 +793,126 @@ if __name__ == "__main__":  # pragma: no cover
     logger.info(f"Difficulties: {diff}")
     logger.info(f"Metadata: {meta}")
 
+# ---------------------------------------------------------------------------
+# MCP Server Integration (Gradio built-in)
+# ---------------------------------------------------------------------------
+
+# Only expose MCP function when running locally (not when deployed to HF Spaces)
+# This is controlled by the USE_HF_WORDS environment variable
+try:
+    import gradio as gr
+    _GRADIO_AVAILABLE = True
+except Exception:
+    _GRADIO_AVAILABLE = False
+
+if _GRADIO_AVAILABLE and not USE_HF_WORDS:
+    @gr.mcp_server_function(
+        name="generate_ai_words",
+        description="""
+        Generate 75 AI-selected words (25 each of lengths 4, 5, 6) related to a topic.
+        
+        This function generates vocabulary words for the Wrdler game using local AI models.
+        It validates words against game constraints and returns difficulty scores.
+        
+        Only available when running locally (USE_HF_WORDS=false).
+        """,
+        input_schema={
+            "type": "object",
+            "properties": {
+                "topic": {
+                    "type": "string",
+                    "description": "Semantic theme for word generation (e.g., 'Ocean Life', 'Space', 'Medieval History')",
+                    "default": "English"
+                },
+                "model_name": {
+                    "type": "string",
+                    "description": "Optional: Override default AI model name",
+                    "default": None
+                },
+                "seed": {
+                    "type": "integer",
+                    "description": "Optional: Random seed for reproducibility",
+                    "default": None
+                },
+                "use_dictionary_filter": {
+                    "type": "boolean",
+                    "description": "Whether to filter words against dictionary (kept for compatibility, currently ignored)",
+                    "default": True
+                },
+                "selected_file": {
+                    "type": "string",
+                    "description": "Optional: Word list file name for dictionary context",
+                    "default": None
+                }
+            },
+            "required": ["topic"]
+        },
+        output_schema={
+            "type": "object",
+            "properties": {
+                "words": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Final 75 words (uppercase A-Z), 25 each of lengths 4, 5, 6"
+                },
+                "difficulties": {
+                    "type": "object",
+                    "description": "Difficulty scores for each word (word -> float)",
+                    "additionalProperties": {"type": "number"}
+                },
+                "metadata": {
+                    "type": "object",
+                    "description": "Generation metadata (model used, counts, diagnostics)",
+                    "properties": {
+                        "model_used": {"type": "string"},
+                        "transformers_available": {"type": "string"},
+                        "gradio_client_available": {"type": "string"},
+                        "use_hf_words": {"type": "string"},
+                        "raw_output_length": {"type": "string"},
+                        "raw_output_snippet": {"type": "string"},
+                        "ai_initial_count": {"type": "string"},
+                        "topic": {"type": "string"},
+                        "dictionary_filter": {"type": "string"},
+                        "new_words_saved": {"type": "string"}
+                    }
+                }
+            }
+        }
+    )
+    def mcp_generate_ai_words(
+        topic: str = "English",
+        model_name: Optional[str] = None,
+        seed: Optional[int] = None,
+        use_dictionary_filter: bool = True,
+        selected_file: Optional[str] = None,
+    ) -> dict:
+        """
+        MCP-compatible wrapper for generate_ai_words function.
+        
+        Returns a dictionary with words, difficulties, and metadata keys.
+        This format is compatible with MCP tool requirements.
+        """
+        words, difficulties, metadata = generate_ai_words(
+            topic=topic,
+            model_name=model_name,
+            seed=seed,
+            use_dictionary_filter=use_dictionary_filter,
+            selected_file=selected_file,
+        )
+        
+        return {
+            "words": words,
+            "difficulties": difficulties,
+            "metadata": metadata
+        }
+    
+    logger.info("✅ MCP server function 'generate_ai_words' registered (local mode)")
+else:
+    if not _GRADIO_AVAILABLE:
+        logger.debug("ℹ️ Gradio not available; MCP function not registered")
+    elif USE_HF_WORDS:
+        logger.debug("ℹ️ USE_HF_WORDS=true; MCP function not registered (remote mode)")
+
 hf_root = os.path.join(TMPDIR, "hf-cache")
 os.makedirs(hf_root, exist_ok=True)