Add Gradio UI and AI Topic Generation Features

Version updated to 0.1.2 with significant enhancements:
- Implemented Gradio UI as an alternative to Streamlit, featuring neon-styled topic display, settings persistence, and a real-time game timer.
- Added AI Topic Generation for custom word lists, integrated into the settings tab.
- Enhanced CSS styling for Gradio interface and ensured compatibility with Gradio 5.50.
- Introduced settings persistence for features like "Enable Free Letters" and "Show Challenge Links."
- Fixed Streamlit caching issues and improved word list loading.
- Updated documentation to reflect new features and UI options.
- Refactored code for better support of new functionalities.

CLAUDE.md

@@ -7,20 +7,37 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords, with these k
 - **No scope/radar visualization**
 - **2 free letter guesses at game start** (all instances of chosen letters are revealed)
 
-**Current Version:** 0.1.1
+**Current Version:** 0.1.2
 **Repository:** https://github.com/Oncorporation/Wrdler.git
 **Live Demo:** [DEPLOYMENT_URL_HERE]
 
 ## Recent Changes
 
-**v0.1.1 (Current):**
+**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
+  - Auto-matches existing wordlist files or uses input as AI topic
+- ✅ **Settings Persistence** - Enable Free Letters and Show Challenge Links persist across new games
+- ✅ **Timer Implementation** - Real-time game timer using gr.Timer component
+  - Timer resets properly on New Game
+  - Stops when game is over
+- ✅ **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 (Previous):**
 - ✅ Enhanced AI word generation logic with intelligent word saving
 - ✅ Automatic retry mechanism for insufficient word counts (up to 3 retries)
-- ✅1000-word file size limit to prevent dictionary bloat
+- ✅ 1000-word file size limit to prevent dictionary bloat
 - ✅ Better new word detection (separates existing vs. new words before saving)
 - ✅ Improved 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 (Previous):**
 - ✅ Version updated to 0.1.0 across all files
@@ -70,7 +87,7 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords, with these k
 ## Technical Architecture
 
 ### Technology Stack
-- **Framework:** Streamlit 1.51.0
+- **Framework:** Streamlit 1.51.0 (primary), Gradio 5.50 (alternative)
 - **Language:** Python 3.12.8 (requires >=3.12, <3.13)
 - **Visualization:** Matplotlib (>=3.8)
 - **HTTP Requests:** requests (>=2.31.0)
@@ -85,12 +102,14 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords, with these k
 wrdler/
 ├── app.py                    # Streamlit entry point
 ├── wrdler/                   # Main package
-│   ├── __init__.py          # Version: 0.1.0
+│   ├── __init__.py          # Version: 0.1.2
 │   ├── models.py            # Data models (Coord, Word, Puzzle, GameState)
 │   ├── generator.py         # Puzzle generation with deterministic seeding
 │   ├── logic.py             # Game mechanics (reveal, guess, scoring)
 │   ├── ui.py                # Streamlit UI
+│   ├── gradio_ui.py         # Gradio UI (alternative interface)
 │   ├── word_loader.py       # Word list management
+│   ├── word_loader_ai.py    # AI word generation with HF Space API
 │   ├── audio.py             # Background music system
 │   ├── sounds.py            # Sound effects management
 │   ├── generate_sounds.py   # Sound generation utilities
@@ -106,6 +125,7 @@ wrdler/
 │       ├── classic.txt      # Default word list
 │       ├── fourth_grade.txt # Elementary word list
 │       └── wordlist.txt     # Full word list
+├── style_wrdler.css         # Custom CSS styling for Gradio interface
 ├── tests/                   # Unit tests
 │   └── test_sprint6_integration.py  # Comprehensive integration tests
 ├── specs/                   # Documentation
@@ -228,7 +248,7 @@ wrdler/
 
 ### Development Status
 
-**Current Version:** 0.1.1 (Complete)
+**Current Version:** 0.1.2 (Complete)
 - ✅ All 7 sprints complete
 - ✅ 100% test coverage (25/25 tests)
 - ✅ AI word generation implemented
@@ -290,10 +310,13 @@ class GameState:
 # Install dependencies
 uv pip install -r requirements.txt --link-mode=copy
 
-# Run app
+# Run Streamlit app (default)
 uv run streamlit run app.py
 # or
 streamlit run app.py
+
+# Run Gradio app (alternative)
+python -m wrdler.gradio_ui
 ```
 
 ### Docker Deployment
@@ -365,6 +388,14 @@ The dataset repository will contain:
 
 ## Post-v0.0.2 Enhancements
 
+### v0.1.2 (Gradio UI Enhancements)
+- Gradio UI Topic Display with neon styling and animations
+- Settings persistence across new games
+- Real-time timer implementation with gr.Timer
+- AI Topic Generation UI in Settings tab
+- Streamlit cache fix for Gradio compatibility
+- Enhanced CSS styling throughout
+
 ### v0.1.1 (AI Word Generation Enhancement)
 - Enhanced AI word generation with intelligent word saving
 - Automatic retry mechanism for insufficient word counts (up to 3 retries)
@@ -373,6 +404,9 @@ The dataset repository will contain:
 - Better HF Space API integration with fallback to local models
 - Additional word generation when MIN_REQUIRED threshold not met
 - Enhanced logging for generation pipeline visibility
+- **Gradio UI implementation** (gradio 5.50) as alternative interface
+- Custom CSS styling for Gradio (style_wrdler.css)
+- Dual UI framework support (Streamlit + Gradio)
 
 ### v0.1.0 (AI Word Generation)
 - AI-powered word list generation using Hugging Face Spaces
@@ -427,6 +461,7 @@ The dataset repository will contain:
 - ✅ Project uses modern Python features (3.12.8)
 - ✅ Requires Python >=3.12, <3.13 per pyproject.toml
 - ✅ Heavy use of Streamlit session state for game state management
+- ✅ Gradio 5.50 state management using gr.State for game persistence
 - ✅ Client-side JavaScript for timer updates without page refresh
 - ✅ CSS heavily customized for ocean theme aesthetics
 - ✅ All file paths should be absolute when working in WSL environment
@@ -438,6 +473,11 @@ The dataset repository will contain:
 - ✅ PWA injection via Docker build script (`inject-pwa-head.sh`)
 - ✅ AI word generation via `word_loader_ai.py` with Hugging Face integration
 - ✅ Utility modules provide reusable functions for storage and file ops
+- ✅ **Gradio 5.50 compatibility:** Using modern gr.Button, gr.State, and event handlers
+  - Reference: [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)
+  - Uses `gr.update()` for component updates
+  - Event handlers use `.click()`, `.change()`, `.submit()` methods
+  - State management via `gr.State(value=...)` with deep copy for updates
 
 ### Key Implementation Details
 - **No radar field in Puzzle dataclass** - removed in Sprint 3
@@ -450,6 +490,13 @@ The dataset repository will contain:
 - **Incorrect guess limit** - maximum 10 per game
 - **AI word generation** - generates 75 words per topic, saves to local files
 - **Utility modules** - shared functions from OpenBadge project
+- **Gradio 5.50 UI implementation**:
+  - Modern component API with `gr.Button`, `gr.Textbox`, `gr.HTML`, etc.
+  - State updates use `copy.deepcopy()` to trigger Gradio reactivity
+  - Event handlers return tuples matching output component order
+  - Custom CSS via `style_wrdler.css` file
+  - Modal dialogs using `gr.Modal(visible=False)` pattern
+  - Reference: [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)
 
 ### WSL Environment Python Versions
 The development environment is WSL (Windows Subsystem for Linux) with access to both native Linux and Windows Python installations:
@@ -475,6 +522,7 @@ This file (CLAUDE.md) serves as a **living context document** for AI-assisted de
 - **[README.md](README.md)** - User-facing documentation, installation guide, and complete changelog
 - **[Dockerfile](Dockerfile)** - Container deployment configuration with PWA injection
 - **[pyproject.toml](pyproject.toml)** - Python project metadata and dependencies
+- **[Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)** - Official Gradio migration reference (external)
 
 **When to use each:**
 - **specs.md** - Understanding game rules and scoring system
@@ -484,6 +532,7 @@ This file (CLAUDE.md) serves as a **living context document** for AI-assisted de
 - **README.md** - Public-facing info, setup instructions, and complete changelog
 - **INSTALL_GUIDE.md** - Installing Wrdler as a PWA
 - **Dockerfile** - Deployment configuration and container setup
+- **Gradio Migration Guide** - Gradio 5.x/6.x compatibility and best practices
 
 ## Challenge Mode & Remote Storage
 
@@ -511,6 +560,7 @@ This file (CLAUDE.md) serves as a **living context document** for AI-assisted de
 
 From `requirements.txt`:
 - streamlit>=1.51.0 (primary framework)
+- gradio>=5.50 (alternative UI framework)
 - matplotlib>=3.8 (visualization)
 - requests>=2.31.0 (HTTP requests)
 - huggingface_hub>=0.20.0 (remote storage)
@@ -523,7 +573,8 @@ From `pyproject.toml`:
 
 ## Version History Summary
 
-- **v0.1.1** (Current) - Enhanced AI word generation with intelligent saving, retry logic, file size limits
+- **v0.1.2** (Current) - Gradio UI Topic Display, settings persistence, timer, enhanced CSS
+- **v0.1.1** (Previous) - Enhanced AI word generation with intelligent saving, retry logic, file size limits
 - **v0.1.0** (Previous) - AI word generation, utility modules, version bump
 - **v0.0.4** - Documentation sync, version update
 - **v0.0.2-0.0.3** - All 7 sprints complete, core Wrdler features
@@ -532,6 +583,6 @@ From `pyproject.toml`:
 
 ---
 
-**Last Updated:** 2025-01-31
-**Current Version:** 0.1.1
-**Status:** Production Ready - AI Enhanced ✅
+**Last Updated:** 2025-11-29
+**Current Version:** 0.1.2
+**Status:** Production Ready - Gradio UI Enhanced ✅

README.md

@@ -1,6 +1,6 @@
 ---
 title: Wrdler
-emoji: 🧩
+emoji: 🎲
 colorFrom: blue
 colorTo: indigo
 sdk: streamlit
@@ -8,10 +8,13 @@ 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
@@ -25,6 +28,10 @@ thumbnail: >-
 
 Wrdler is a vocabulary learning game with a simplified grid and strategic letter guessing. The objective is to discover hidden words on a grid by making smart guesses before all letters are revealed.
 
+**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)
@@ -82,8 +89,13 @@ Wrdler is a vocabulary learning game with a simplified grid and strategic letter
 
 ### 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
@@ -121,15 +133,21 @@ When playing a shared challenge (via a `game_id` link), the leaderboard displays
 
 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
 ```
 
-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.
@@ -172,13 +190,17 @@ CRYPTO_PK=                             # Reserved for future signing
 - `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
- - `words/wordlist.txt` – candidate words
+ - `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
 
@@ -196,7 +218,18 @@ All test files must be placed in the `/tests` folder. This ensures a clean proje
 
 ## Changelog
 
-### v0.1.1 (Current)
+### 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
@@ -204,6 +237,9 @@ All test files must be placed in the `/tests` folder. This ensures a clean proje
 - ✅ 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
@@ -244,7 +280,7 @@ Note
 
 ## 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 persistence to ensure the chosen file is correctly used by the generator.
+- 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
 
@@ -260,10 +296,11 @@ Wrdler is based on BattleWords. BattlewordsTM. All Rights Reserved. All content,
 
 ## Hugging Face Spaces Configuration
 
-Wrdler is deployable as a Hugging Face Space. You can use either the YAML config block or a Dockerfile for advanced/custom deployments.
+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
@@ -274,128 +311,415 @@ 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` for Streamlit apps.
-- `sdk_version`: Latest supported Streamlit version.
-- `python_version`: Python version (default is3.10).
-- `app_file`: Entry point for your app.
+- `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.
 
-**Dependencies:** 
-Add a `requirements.txt` with your Python dependencies (e.g., `streamlit`, etc.).
+**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
 
-**Port:** 
-Streamlit Spaces use port `8501` by default.
+````````
 
-**Embedding:**
-Spaces can be embedded in other sites using an `<iframe>`:
+# 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
+---
 
-```html
-<iframe src="https://[YourUsername]-Wrdler.hf.space?embed=true" title="Wrdler"></iframe>
-```
+# Wrdler
 
-For full configuration options, see [Spaces Config Reference](https://huggingface.co/docs/hub/spaces-config-reference) and [Streamlit SDK Guide](https://huggingface.co/docs/hub/spaces-sdks-streamlit).
+> **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.**
 
-# Assets Setup
+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.
 
-To fully experience Wrdler, especially the audio elements, ensure you set up the following assets:
+**Dual UI Support:** Play with Streamlit (default) or Gradio 5.50+ (alternative) - same great gameplay, your choice of framework!
 
-- Place your background music `.mp3` files in `wrdler/assets/audio/music/` to enable music.
-- Place your sound effect files (`.mp3` or `.wav`) in `wrdler/assets/audio/effects/` for sound effects.
+**🎮 Live Demo:** [Play on Hugging Face Spaces](https://huggingface.co/spaces/Surn/Wrdler)
 
-Refer to the documentation for guidance on compatible audio formats and common troubleshooting tips.
+## Key Differences from BattleWords
 
-# Sound Asset Generation
+- **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
 
-To generate and save custom sound effects for Wrdler, you can use the `generate_sound_effect` function.
+## Features
 
-## Function: `generate_sound_effect`
+### 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)
 
-```python
-def generate_sound_effect(effect: str, save_to_assets: bool = False, use_api: str = "huggingface") -> str:
- """
- Generate a sound effect and save it as a file.
+### 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
 
- Parameters:
- - `effect`: Name of the effect to generate.
- - `save_to_assets`: If `True`, saves the effect to the assets directory; 
- if `False`, saves to a temporary location. Default is `False`.
- - `use_api`: API to use for generation. Options are "huggingface" or "replicate". Default is "huggingface".
+### 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
 
- Returns:
- - File path to the saved sound effect.
+### 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 
  ```
 
-## Parameters
 
-- `effect`: The name of the sound effect you want to generate (e.g., "explosion", "powerup").
-- `save_to_assets` (optional): Set to `True` to save the generated sound effect to the game's assets directory. If `False`, the effect is saved to a temporary location. Default is `False`.
-- `use_api` (optional): The API to use for generating the sound. Options are `"huggingface"` or `"replicate"`. Default is `"huggingface"`.
+## 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
+```
 
-## Returns
+Both interfaces provide the same gameplay experience with slightly different UI frameworks.
 
-- The function returns the file path to the saved sound effect, whether it's in the assets directory or a temporary location.
+### Dockerfile Deployment (Hugging Face Spaces and more)
 
-## Usage Example
+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 generate a sound effect and save it to the assets directory:
+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.
 
-```python
-generate_sound_effect("your_effect_name", save_to_assets=True)
+For local Docker runs:
+```sh
+docker build -t wrdler .
+docker run -p8501:8501 wrdler
 ```
 
-To generate a sound effect and keep it in a temporary location:
+### Environment Variables (for Challenge Mode)
+
+Challenge Mode requires a `.env` file in the project root with HuggingFace Hub credentials:
 
-```python
-temp_path = generate_sound_effect("your_effect_name", save_to_assets=False)
+```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
 ```
 
-## Note
+**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_...`
 
-Ensure you have the necessary permissions and API access (if required) to use the sound generation service. Generated sounds are subject to the terms of use of the respective API.
+**Note:** The app works without these variables, but Challenge Mode features (sharing, leaderboards) will be disabled.
 
-For any issues or enhancements, please refer to the project documentation or contact the project maintainer.
+## Folder Structure
 
-Happy gaming and sound designing!
+- `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
 
-## What's New in v0.2.20-0.2.27: Challenge Mode 🎯
+## 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.
 
-### Remote Challenge Sharing 🔗
-- Share challenges with friends via short URLs (`?game_id=<sid>`)
-- Each player gets different random words from the same wordlist
-- Multi-user leaderboards sorted by score and time
-- Word list difficulty calculation and display
-- Compare your performance against others!
-
-### Leaderboards 🏆
-- Top 5 players displayed in Challenge Mode banner
-- Results sorted by: highest score → fastest time → highest difficulty
-- Submit results to existing challenges or create new ones
-- Player names supported (optional, defaults to "Anonymous")
-
-### Remote Storage 💾
-- Challenge data stored in Hugging Face dataset repositories
-- Automatic save on game completion (with user consent)
-- "Show Challenge Share Links" toggle for privacy control (default OFF)
-- Works offline when HF credentials not configured
-
-## What's Planned for v0.3.0
-
-### Local Player History (Coming Soon)
-- Personal game results saved locally in `~/.wrdler/data/`
-- Offline-capable high score tracking
-- Player statistics (games played, averages, bests)
-- Privacy-first: no cloud dependency for personal data
-- Easy data management (delete `~/.wrdler/data/` to reset)
-
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+## 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

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wrdler"
-version = "0.1.0"
+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"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

requirements.txt

@@ -13,4 +13,5 @@ requests
 huggingface_hub
 python-dotenv
 google-api-core
-gradio>=4.0.0
+gradio>=5.50
+gradio-modal

specs/requirements.md

@@ -15,14 +15,21 @@ This document breaks down the implementation tasks for Wrdler using the game rul
 - 2 free letter guesses at game start
 
 ## Implementation Details (v0.1.1)
-- **Tech Stack:** Python 3.12.8, Streamlit 1.51.0, numpy, matplotlib, transformers, gradio_client
-- **Architecture:** Single-player, local state in Streamlit session state
+- **Tech Stack:** Python 3.12.8, Streamlit 1.51.0, Gradio 5.50, numpy, matplotlib, transformers, gradio_client
+- **Architecture:** Single-player, local state in Streamlit session state or Gradio gr.State
 - **Grid:** 8 columns × 6 rows (48 cells) with exactly six words
 - **Word Placement:** Horizontal-only, one word per row, no overlaps
 - **AI Generation:** Topic-based word lists with intelligent saving and retry logic
-- **Entry Point:** `app.py`
+- **Entry Points:** 
+  - Streamlit: `app.py`
+  - Gradio: `wrdler/gradio_ui.py` or `python -m wrdler.gradio_ui`
 - **Testing:** pytest with 25/25 tests passing (100%)
 - **Development Time:** ~12.75 hours across 7 sprints (Phase 1) + AI enhancements
+- **Gradio Implementation:** Modern API compatible with Gradio 5.50+
+  - Reference: [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)
+  - Uses gr.State for game persistence
+  - Event handlers with modern `.click()`, `.change()`, `.submit()` methods
+  - Custom CSS styling via external file
 
 ## Streamlit Components (Implemented in v0.0.2)
 - State & caching ✅
@@ -57,6 +64,44 @@ This document breaks down the implementation tasks for Wrdler using the game rul
   - App reruns on interaction using `st.rerun()`
   - Game over dialog with final score and tier display
 
+## Gradio Components (Implemented in v0.1.1)
+- State management ✅
+  - `gr.State(value=create_new_game_state)` for game persistence
+  - State updates use `copy.deepcopy()` to trigger reactivity
+  - Serializable state dict (no complex objects in state)
+
+- Layout & structure ✅
+  - `gr.Blocks()` with custom theme (`theme="Surn/beeuty"`)
+  - `gr.Tabs()` for Game and Settings sections
+  - `gr.Row()` and `gr.Column()` for responsive layout
+  - `gr.Modal()` for share challenge dialog
+
+- Widgets (interaction) ✅
+  - 48 `gr.Button` components for grid cells with dynamic updates
+  - 26 `gr.Button` components for letter selection (only puzzle letters visible)
+  - `gr.Textbox` for word guessing with `.submit()` handler
+  - `gr.Button` for actions (New Game, Guess, Share Challenge)
+  - `gr.Dropdown` for settings (wordlist, game mode)
+  - `gr.Checkbox` for toggles (audio, display options)
+  - `gr.Slider` for volume controls
+
+- Visualization ✅
+  - `gr.HTML()` for score panel with custom styling
+  - `gr.HTML()` for audio player (sound effects)
+  - `gr.HTML()` for game over display
+  - Custom CSS via `style_wrdler.css` file
+  - Responsive grid layout with CSS Grid
+
+- Control flow ✅
+  - Event handlers return component update tuples
+  - `.click()`, `.change()`, `.submit()` for events
+  - `gr.update()` for conditional component updates
+  - State mutations trigger UI updates
+
+- Reference ✅
+  - [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)
+  - Compatible with Gradio 5.50+ API
+
 ## Folder Structure (Implemented)
 - `app.py` – Streamlit entry point ✅
 - `wrdler/` – Python package ✅
@@ -290,3 +335,75 @@ Return 75 Words for Game
 
 ## 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.
+
+## Gradio 5.50 Implementation Reference
+
+### Migration from Gradio 4.x to 5.x
+The Gradio UI implementation follows modern Gradio 5.50+ patterns, compatible with the upcoming Gradio 6 release:
+
+**Official Reference:** [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)
+
+### Key Gradio Patterns Used
+
+1. **State Management**
+   ```python
+   game_state = gr.State(value=create_new_game_state)
+   # Updates use deep copy to trigger reactivity
+   new_state = copy.deepcopy(state)
+   new_state["score"] = 42
+   return new_state
+   ```
+
+2. **Component Updates**
+   ```python
+   # Dynamic button updates
+   gr.Button(value="X", variant="primary", interactive=True)
+   # Conditional visibility
+   gr.update(visible=True)
+   ```
+
+3. **Event Handlers**
+   ```python
+   button.click(
+       fn=handler_function,
+       inputs=[input1, input2, state],
+       outputs=[output1, output2, state]
+   )
+   ```
+
+4. **Modal Dialogs**
+   ```python
+   with gr.Modal(visible=False, elem_id="modal-id") as modal:
+       gr.Markdown("Modal content")
+   ```
+
+5. **Custom CSS**
+   ```python
+   with gr.Blocks(css=css_content, theme="Surn/beeuty") as demo:
+       # Components
+   ```
+
+### Component Compatibility
+- ✅ `gr.Button` - Modern button API with variant, size, interactive params
+- ✅ `gr.Textbox` - Text input with submit handler support
+- ✅ `gr.HTML` - Custom HTML rendering for score panels and audio
+- ✅ `gr.State` - Serializable state management
+- ✅ `gr.Dropdown` - Selection widgets for settings
+- ✅ `gr.Checkbox` - Boolean toggles
+- ✅ `gr.Slider` - Numeric value controls
+- ✅ `gr.Tabs` - Multi-section layout
+- ✅ `gr.Modal` - Dialog overlays
+- ✅ `gr.Row` / `gr.Column` - Responsive layout containers
+
+### Best Practices
+1. **State must be JSON-serializable** - Use dicts/lists, not complex objects
+2. **Deep copy for updates** - `copy.deepcopy(state)` triggers reactivity
+3. **Return tuples matching outputs** - Order matters for component updates
+4. **Use elem_id for CSS targeting** - Consistent IDs for custom styling
+5. **Handle None/undefined gracefully** - Check state initialization
+6. **Batch updates efficiently** - Return all component changes together
+
+### File Structure
+- `wrdler/gradio_ui.py` - Main Gradio interface implementation
+- `style_wrdler.css` - Custom CSS for Gradio components
+- Both files use Gradio 5.50+ compatible patterns

specs/specs.md

@@ -133,7 +133,10 @@ Wrdler is a simplified vocabulary puzzle game based on BattleWords, but with key
 
 ## Entry Point
 - The Streamlit entry point is `app.py`
+- The Gradio entry point is `wrdler/gradio_ui.py` (alternative interface)
 - **A `Dockerfile` can be used for containerized deployment (recommended for Hugging Face Spaces)**
+- **Gradio 5.50 compatibility**: Uses modern component API and event handlers
+  - Reference: [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)
 
 ## Deployment Requirements
 
@@ -199,6 +202,11 @@ HF_REPO_ID/
   - 1000-word file size limit
   - Improved HF Space API integration
   - Enhanced logging and error handling
+  - **Gradio 5.50 UI implementation** as alternative to Streamlit
+    - Modern component API (gr.Button, gr.State, gr.Modal)
+    - Custom CSS styling via style_wrdler.css
+    - Full feature parity with Streamlit version
+    - Reference: [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)
   
 - **v0.1.0:** AI word generation foundation
   - Topic-based word list creation

style_wrdler.css

@@ -1,6 +1,39 @@
 /* Wrdler - Custom CSS for Gradio App */
 /* Based on Surn/beeuty theme patterns */
 
+/* ============================================
+   Override Gradio Theme Disabled Button Styling
+   Lighten up disabled buttons - reduce grayscale
+   ============================================ */
+button[disabled],
+button[disabled].svelte-o34uqh,
+a.disabled,
+a.disabled.svelte-o34uqh,
+button:disabled,
+button[aria-disabled="true"] {
+  opacity: 0.65 !important;  /* Increased from 0.5 for lighter appearance */
+  filter: grayscale(30%) !important;  /* Reduced from 30% for less graying */
+  cursor: not-allowed !important;
+  transform: none !important;
+  color: rgba(0,0,0,0.90);
+}
+
+/* Specific override for letter buttons when used */
+.letter-btn-used button,
+.letter-btn-used button[disabled],
+.letter-btn-used button:disabled {
+  opacity: 0.5 !important;  /* Even lighter for better visibility */
+  filter: grayscale(25%) !important;  /* Minimal grayscale */
+}
+
+/* Specific override for grid cell buttons when revealed */
+.grid-cell-revealed button,
+.grid-cell-revealed button[disabled],
+.grid-cell-revealed button:disabled {
+  opacity: 1 !important;  /* Full opacity for revealed cells */
+  filter: none !important;  /* No filter at all for revealed cells */
+}
+
 .interface-wrapper {
     max-width: 1200px;
     margin: 0 auto;
@@ -20,9 +53,9 @@
     border-radius: 1.25rem;
     overflow: hidden;
     box-shadow: 0 4px 20px rgba(0, 0, 0, 0.3);
-    max-width: 520px;
+    max-width: 92.5%;
     margin: 0 auto 16px auto;
-    font-weight: 600;
+    font-weight: 700;
 }
 
 /* Inner container with original grid colors */
@@ -120,16 +153,36 @@
     padding: 0 !important;
     background: linear-gradient(145deg, #d4f1f9, #a8e6cf) !important;
     border: 2px solid #00bfa5 !important;
-    color: #1a1a2e !important;
+    color: #000000 !important;  /* Changed from #1a1a2e to pure black for maximum contrast */
     cursor: default !important;
+    text-shadow: 0 0 1px rgba(255, 255, 255, 0.3) !important;  /* Subtle white shadow for readability */
 }
 
-/* Empty revealed cells (middle dot) */
+/* Empty revealed cells - solid dark grey fill */
 .grid-cell-revealed button:has(span:empty),
-.grid-cell-revealed button[value="·"] {
+.grid-cell-revealed button[value="·"],
+.grid-cell-revealed button[value=""] {
     background: #2d2d44 !important;
     border: 2px solid #3d3d5c !important;
-    color: #5d5d7c !important;
+    color: transparent !important;  /* Hide any text content */
+    text-shadow: none !important;
+    font-size: 0 !important;  /* Collapse any text rendering */
+    position: relative !important;
+    overflow: hidden !important;
+}
+
+/* Ensure empty cells are completely filled with dark grey */
+.grid-cell-revealed button:has(span:empty)::before,
+.grid-cell-revealed button[value="·"]::before,
+.grid-cell-revealed button[value=""]::before {
+    content: '' !important;
+    position: absolute !important;
+    top: 0 !important;
+    left: 0 !important;
+    width: 100% !important;
+    height: 100% !important;
+    background: #2d2d44 !important;
+    z-index: 1 !important;
 }
 
 /* Legacy CSS for HTML grid (kept for compatibility) */
@@ -632,7 +685,7 @@
 }
 
 .tabitem {
-    background: linear-gradient(145deg, rgba(26, 26, 46, 0.5), rgba(22, 33, 62, 0.5)) !important;
+    background: linear-gradient(145deg, rgba(26, 26, 46, 0.3), rgba(22, 33, 62, 0.5)) !important;
     border-radius: 0 0 12px 12px !important;
     padding: 16px !important;
 }
@@ -649,3 +702,281 @@
     min-width: 200px !important;
     margin-top: 16px !important;
 }
+
+/* Share Challenge Section */
+.share-challenge-section {
+    margin-top: 16px;
+    padding: 16px;
+    background: linear-gradient(-45deg, #1d64c8, #ffffff, #1d64c8, #666666);
+    border-radius: 1rem;
+    box-shadow: 0 0 32px rgba(29, 100, 200, 0.5);
+}
+
+.share-challenge-section h3 {
+    color: #fff !important;
+    text-shadow: 1px 1px 2px rgba(0,0,0,0.3);
+}
+
+.share-challenge-section label {
+    color: #fff !important;
+}
+
+.share-challenge-section input {
+    background: rgba(0,0,0,0.2) !important;
+    color: #fff !important;
+    border: 1px solid rgba(255,255,255,0.3) !important;
+}
+
+.share-challenge-section button {
+    background: linear-gradient(145deg, #00bfa5, #00d2ff) !important;
+    color: #fff !important;
+}
+
+.share-challenge-section button:hover {
+    filter: brightness(1.1);
+}
+
+.share-challenge-result {
+    margin-top: 16px;
+    padding: 12px;
+    background: rgba(0, 191, 165, 0.2);
+    border-radius: 8px;
+    text-align: center;
+}
+
+.share-challenge-result h3 {
+    color: #00d2ff;
+    margin-bottom: 8px;
+}
+
+/* Share Challenge Trigger Button */
+.share-challenge-trigger button {
+    background: linear-gradient(-45deg, #1d64c8, #00bfa5) !important;
+    color: #fff !important;
+    font-weight: 700 !important;
+    padding: 12px 24px !important;
+    font-size: 1.1rem !important;
+    border: none !important;
+    box-shadow: 0 0 20px rgba(29, 100, 200, 0.4) !important;
+}
+
+.share-challenge-trigger button:hover {
+    filter: brightness(1.1);
+    box-shadow: 0 0 30px rgba(29, 100, 200, 0.6) !important;
+}
+
+/* Share Challenge Modal */
+.share-challenge-modal {
+    background: linear-gradient(-45deg, #1d64c8, #ffffff, #1d64c8, #666666) !important;
+    border-radius: 1rem !important;
+    box-shadow: 0 0 50px rgba(29, 100, 200, 0.5) !important;
+}
+
+.share-challenge-modal h2 {
+    color: #fff !important;
+    text-shadow: 1px 1px 3px rgba(0,0,0,0.3);
+}
+
+.share-challenge-modal p {
+    color: #fff !important;
+}
+
+.share-challenge-modal label {
+    color: #fff !important;
+}
+
+.share-challenge-modal input {
+    background: rgba(0,0,0,0.2) !important;
+    color: #fff !important;
+    border: 1px solid rgba(255,255,255,0.3) !important;
+}
+
+.share-challenge-modal button {
+    margin-top: 8px !important;
+}
+
+/* ============================================
+   Topic Display - Prominent Inline Badge Style
+   ============================================ */
+div:has(> #topic-display) {
+    display: flex;
+    flex-direction: inherit;
+    flex-wrap: wrap;
+    gap: unset !important;
+    box-shadow: none !important;
+    border: none !important;
+    border-radius: var(--block-radius);
+    background: none !important;
+}
+/* Topic container - center and constrain width */
+#topic-display {
+    max-width: 90% !important;
+    margin: 0 auto 16px auto !important;
+    border: none !important;
+    background: transparent !important;
+}
+
+/* Hide the label span but keep the label container */
+#topic-display span.sr-only,
+#topic-display span.hide {
+    display: none !important;
+}
+
+/* Style the label container */
+#topic-display label.container {
+    background: transparent !important;
+    border: none !important;
+    padding: 0 !important;
+}
+
+/* Style the input container */
+#topic-display .input-container {
+    background: transparent !important;
+    border: none !important;
+}
+
+/* The actual input - styled as a glowing badge with theme colors */
+/* Using multiple selectors for maximum specificity */
+#topic-display input,
+#topic-display input[type="text"],
+#topic-display input.scroll-hide,
+#topic-display .input-container input,
+div#topic-display input,
+.topic-input input,
+div.topic-input input,
+#topic-display label input,
+#topic-display label.container input {
+    /* Dark background matching grid container */
+    background: linear-gradient(145deg, #1a1a2e, #16213e) !important;
+
+    /* Glowing border with theme cyan */
+    border: 2px solid #00d2ff !important;
+    border-radius: 50px !important;
+
+    /* Typography - theme colors */
+    padding: 12px 32px !important;
+    font-size: 1.4rem !important;
+    font-weight: 700 !important;
+    color: #00d2ff !important;  /* Theme cyan color */
+    text-align: center !important;
+    text-transform: uppercase !important;
+    letter-spacing: 2px !important;
+    -webkit-text-fill-color: #00d2ff !important;
+    caret-color: #00bfa5 !important;  /* Theme teal for caret */
+
+    /* Neon glow effect with theme colors */
+    box-shadow:
+        0 0 10px rgba(0, 210, 255, 0.5),
+        0 0 20px rgba(0, 210, 255, 0.3),
+        0 0 40px rgba(0, 191, 165, 0.2),
+        inset 0 0 30px rgba(0, 210, 255, 0.1) !important;
+    text-shadow:
+        0 0 10px rgba(0, 210, 255, 0.8),
+        0 0 20px rgba(0, 210, 255, 0.5),
+        0 0 30px rgba(0, 191, 165, 0.3);
+
+    /* Sizing */
+    width: 100% !important;
+    min-height: 48px !important;
+    height: 48px !important;
+    line-height: 24px !important;
+
+    /* Ensure visibility */
+    opacity: 1 !important;
+    visibility: visible !important;
+
+    /* Animation */
+    transition: all 0.3s ease !important;
+    animation: topic-neon-pulse 2.5s ease-in-out infinite;
+}
+
+/* Neon pulse animation - theme colors */
+@keyframes topic-neon-pulse {
+    0%, 100% {
+        box-shadow:
+            0 0 10px rgba(0, 210, 255, 0.4),
+            0 0 20px rgba(0, 210, 255, 0.3),
+            0 0 40px rgba(0, 191, 165, 0.2),
+            inset 0 0 15px rgba(0, 210, 255, 0.1);
+        border-color: #00d2ff;
+    }
+    50% {
+        box-shadow:
+            0 0 15px rgba(0, 210, 255, 0.6),
+            0 0 30px rgba(0, 210, 255, 0.4),
+            0 0 60px rgba(0, 191, 165, 0.3),
+            inset 0 0 20px rgba(0, 210, 255, 0.15);
+        border-color: #00bfa5;  /* Alternates to teal */
+    }
+}
+
+/* Hover state - intensified glow with theme colors */
+#topic-display input:hover,
+div#topic-display input:hover,
+.topic-input input:hover {
+    background: linear-gradient(145deg, #16213e, #1a1a2e) !important;
+    border-color: #00bfa5 !important;  /* Theme teal */
+    color: #00bfa5 !important;
+    -webkit-text-fill-color: #00bfa5 !important;
+    box-shadow:
+        0 0 15px rgba(0, 191, 165, 0.6),
+        0 0 30px rgba(0, 210, 255, 0.4),
+        0 0 50px rgba(0, 191, 165, 0.3),
+        inset 0 0 40px rgba(0, 210, 255, 0.15) !important;
+    cursor: text;
+}
+
+/* Focus state - editing mode with bright glow */
+#topic-display input:focus,
+div#topic-display input:focus,
+.topic-input input:focus {
+    background: linear-gradient(145deg, #1a1a2e, #0d0d1a) !important;
+    outline: none !important;
+    border-color: #00bfa5 !important;
+    color: #a8e6cf !important;  /* Lighter teal for active editing */
+    -webkit-text-fill-color: #a8e6cf !important;
+    box-shadow:
+        0 0 20px rgba(0, 191, 165, 0.8),
+        0 0 40px rgba(0, 210, 255, 0.5),
+        0 0 60px rgba(0, 191, 165, 0.3),
+        inset 0 0 50px rgba(0, 210, 255, 0.2) !important;
+    animation: none !important;
+}
+
+/* Placeholder styling - theme colors */
+#topic-display input::placeholder,
+div#topic-display input::placeholder,
+.topic-input input::placeholder {
+    color: rgba(0, 210, 255, 0.5) !important;  /* Muted cyan */
+    -webkit-text-fill-color: rgba(0, 210, 255, 0.5) !important;
+    font-style: italic;
+    text-transform: none !important;
+    letter-spacing: normal !important;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+    #topic-display {
+        max-width: 350px !important;
+    }
+
+    #topic-display textarea,
+    #topic-display input {
+        font-size: 1.2rem !important;
+        padding: 10px 24px !important;
+        letter-spacing: 1px !important;
+    }
+}
+
+@media (max-width: 480px) {
+    #topic-display {
+        max-width: 280px !important;
+    }
+
+    #topic-display textarea,
+    #topic-display input {
+        font-size: 1rem !important;
+        padding: 8px 20px !important;
+        letter-spacing: 0.5px !important;
+    }
+}

wrdler/__init__.py

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

wrdler/gradio_ui.py

@@ -17,6 +17,7 @@ import base64
 import mimetypes
 
 import gradio as gr
+from gradio_modal import Modal
 
 from .models import Coord, Word, Puzzle, GameState
 from .logic import (
@@ -29,6 +30,13 @@ from .logic import (
     compute_tier,
 )
 from .generator import generate_puzzle
+from .game_storage import (
+    save_game_to_hf,
+    add_user_result_to_game,
+    get_shareable_url,
+    load_game_from_sid
+)
+from .word_loader_ai import generate_ai_words
 
 # Version info
 from . import __version__
@@ -215,10 +223,51 @@ def load_word_list_gradio(selected_file: Optional[str] = None) -> Dict[int, List
 def create_new_game_state(
     wordlist: str = "classic.txt",
     game_mode: str = "classic",
-    seed: Optional[int] = None
+    seed: Optional[int] = None,
+    ai_topic: str = ""
 ) -> Dict[str, Any]:
     """Create a new game state dictionary for gr.State."""
-    words_by_len = load_word_list_gradio(wordlist)
+    # Handle AI Generated word list
+    if wordlist == "AI Generated" and ai_topic.strip():
+        import re as re_module
+        # Convert topic to filename (same logic as _save_ai_words_to_file)
+        safe_topic = re_module.sub(r'[^\w\s-]', '', ai_topic.strip().lower()).strip()
+        safe_topic = re_module.sub(r'[-\s]+', '_', safe_topic)
+        topic_filename = f"{safe_topic}.txt"
+
+        # First try to load existing words from the topic file
+        words_by_len = None
+        try:
+            existing_words = load_word_list_gradio(topic_filename)
+            # Check if we have enough words of each length
+            has_enough = all(len(existing_words.get(length, [])) >= MIN_REQUIRED for length in (4, 5, 6))
+            if has_enough:
+                words_by_len = existing_words
+        except Exception:
+            pass
+
+        # If no existing file or not enough words, generate new AI words
+        if words_by_len is None:
+            try:
+                # Generate AI words - returns list of 75 words
+                ai_words, _, _ = generate_ai_words(topic=ai_topic.strip())
+                # Convert to words_by_len format
+                words_by_len = {4: [], 5: [], 6: []}
+                for word in ai_words:
+                    word_len = len(word)
+                    if word_len in words_by_len:
+                        words_by_len[word_len].append(word.upper())
+                # Ensure we have enough words of each length
+                for length in (4, 5, 6):
+                    if len(words_by_len[length]) < MIN_REQUIRED:
+                        # Fall back to default words
+                        words_by_len[length] = FALLBACK_WORDS[length].copy()
+            except Exception as e:
+                # Fall back to default word list on error
+                words_by_len = load_word_list_gradio("classic.txt")
+    else:
+        words_by_len = load_word_list_gradio(wordlist if wordlist != "AI Generated" else "classic.txt")
+
     puzzle = generate_puzzle(
         grid_rows=GRID_ROWS,
         grid_cols=GRID_COLS,
@@ -260,6 +309,10 @@ def create_new_game_state(
         "music_enabled": False,
         "music_volume": 30,
         "pending_sound": None,  # Sound effect to play on next render
+        # Display settings
+        "show_incorrect_guesses": True,
+        "enable_free_letters": True,
+        "show_challenge_links": True,
         # Challenge mode
         "challenge_mode": False,
         "challenge_sid": None,
@@ -441,6 +494,10 @@ def get_all_letter_button_updates(state: Dict[str, Any], all_puzzle_letters: Lis
 
 def render_free_letters_status(state: Dict[str, Any]) -> str:
     """Generate status message for free letter selection."""
+    # Check if free letters are enabled
+    if not state.get("enable_free_letters", True):
+        return ""
+
     letters_used = state.get("free_letters_used", 0)
 
     if letters_used >= MAX_FREE_LETTERS:
@@ -458,6 +515,8 @@ def render_score_panel_html(state: Dict[str, Any]) -> str:
     start_time = state["start_time"]
     end_time = state["end_time"]
     game_over = state["game_over"]
+    incorrect_guesses = state.get("incorrect_guesses", [])
+    show_incorrect = state.get("show_incorrect_guesses", True)
 
     # Calculate elapsed time
     if end_time:
@@ -500,34 +559,33 @@ def render_score_panel_html(state: Dict[str, Any]) -> str:
 
     table_inner = "\n".join(table_rows)
 
-    # Timer HTML
-    if not game_over:
-        timer_html = f'''
-<div class="timer" id="wrdler-timer" data-start="{start_time}">
-    Time: <span class="time-value">{time_str}</span>
-</div>
-<script>
-(function() {{
-    const timerEl = document.getElementById('wrdler-timer');
-    if (!timerEl) return;
-    const startTime = new Date(timerEl.dataset.start);
-    function updateTimer() {{
-        const now = new Date();
-        const elapsed = Math.floor((now - startTime) / 1000);
-        const mins = Math.floor(elapsed / 60);
-        const secs = elapsed % 60;
-        const timeSpan = timerEl.querySelector('.time-value');
-        if (timeSpan) {{
-            timeSpan.textContent = String(mins).padStart(2, '0') + ':' + String(secs).padStart(2, '0');
-        }}
-    }}
-    setInterval(updateTimer, 1000);
-    updateTimer();
-}})();
-</script>
-'''
-    else:
-        timer_html = f'<div class="timer">Time: <span class="time-value">{time_str}</span></div>'
+    # Timer HTML - calculate current elapsed time
+    if not game_over and start_time:
+        try:
+            start = datetime.fromisoformat(start_time)
+            now = datetime.now()
+            elapsed = (now - start).total_seconds()
+            minutes = int(elapsed // 60)
+            seconds = int(elapsed % 60)
+            time_str = f"{minutes:02d}:{seconds:02d}"
+        except Exception:
+            pass
+
+    timer_html = f'<div class="timer">Time: <span class="time-value">{time_str}</span></div>'
+
+    # Incorrect guesses HTML
+    incorrect_html = ""
+    if show_incorrect and incorrect_guesses:
+        recent = incorrect_guesses[-10:]  # Show last 10
+        guess_items = "".join(f'<div class="guess-item">• {g}</div>' for g in recent)
+        incorrect_html = f'''
+        <div class="wrdler-incorrect-guesses">
+            <details>
+                <summary>Incorrect guesses ({len(incorrect_guesses)})</summary>
+                <div class="guess-list">{guess_items}</div>
+            </details>
+        </div>
+        '''
 
     html = f'''
     <div class='wrdler-score-panel-container'>
@@ -550,12 +608,18 @@ def render_score_panel_html(state: Dict[str, Any]) -> str:
         .wrdler-score-panel-container tr {{ border-bottom: 1px solid rgba(0, 0, 0, 0.1); background: #000;}}
         .wrdler-score-panel-container tr.found td {{ font-weight: 600; background: #000;}}
         .wrdler-score-panel-container tr.hidden td {{ color: #333; }}
+        .wrdler-incorrect-guesses {{ margin-top: 12px; padding: 8px; background: rgba(255, 100, 100, 0.15); border-radius: 8px; }}
+        .wrdler-incorrect-guesses summary {{ color: #ff9999; font-size: 0.85rem; cursor: pointer; font-weight: 600; }}
+        .wrdler-incorrect-guesses summary:hover {{ color: #ffaaaa; }}
+        .wrdler-incorrect-guesses .guess-list {{ color: #ff9999; font-size: 0.8rem; margin-top: 6px; padding-left: 8px; }}
+        .wrdler-incorrect-guesses .guess-item {{ margin: 2px 0; }}
       </style>
       <div class="score-header">Score: <span class="score-value">{score}</span></div>
-      {timer_html}      
+      {timer_html}
       <table class='shiny-border' style=\"border-radius:0.75rem; overflow:hidden; width:100%; margin:0 auto; border-collapse:separate; border-spacing: 0;\">
         {table_inner}
       </table>
+      {incorrect_html}
     </div>
     '''
 
@@ -651,6 +715,20 @@ def render_game_over_html(state: Dict[str, Any]) -> str:
         html.append(f'<tr><td>{text}</td><td>{base}</td><td>+{bonus}</td><td>{points}</td></tr>')
 
     html.append('</table></div>')
+
+    # Show share URL if already generated
+    share_url = state.get("share_url")
+    if share_url:
+        html.append(f'''
+        <div class="share-challenge-result">
+            <h3>Share Your Challenge</h3>
+            <p style="color: #00bfa5; font-weight: 600;">Share link generated!</p>
+            <div class="share-url-display">
+                <code style="background: rgba(0,0,0,0.3); padding: 8px 12px; border-radius: 6px; display: block; word-break: break-all; color: #fff;">{share_url}</code>
+            </div>
+        </div>
+        ''')
+
     html.append('</div>')
 
     return "\n".join(html)
@@ -707,11 +785,19 @@ 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.
 
-    Returns: (48 grid buttons, 26 letter buttons, score_panel, status_msg, audio, game_over, free_letter_status, state)
+    Returns: (48 grid buttons, 26 letter buttons, score_panel, status_msg, audio, game_over, free_letter_status, free_letter_row, share_btn, state)
     """
     grid_button_updates = get_all_button_updates(state)
     letter_button_updates = get_letter_button_updates(state)
 
+    # Show share button only when game is over AND show_challenge_links is enabled
+    show_share = state.get("game_over", False) and state.get("show_challenge_links", True)
+    share_btn_visible = gr.Button(visible=show_share)
+
+    # Show free letter section only if enabled
+    show_free_letters = state.get("enable_free_letters", True)
+    free_letter_row_visible = gr.Row(visible=show_free_letters)
+
     return (
         *grid_button_updates,  # 48 grid button updates
         *letter_button_updates,  # 26 letter button updates
@@ -719,7 +805,9 @@ def build_ui_outputs(state: Dict[str, Any], audio_html: str = "") -> tuple:
         state.get("last_action", ""),
         audio_html,
         render_game_over_html(state),
-        render_free_letters_status(state),
+        render_free_letters_status(state) if show_free_letters else "",
+        free_letter_row_visible,
+        share_btn_visible,
         state
     )
 
@@ -737,8 +825,9 @@ def handle_cell_click(row: int, col: int, state: Dict[str, Any]) -> tuple:
     if state.get("game_over"):
         return build_ui_outputs(state)
 
-    # Check if free letters required first
-    if state["free_letters_used"] < MAX_FREE_LETTERS:
+    # Check if free letters required first (only if free letters are enabled)
+    free_letters_enabled = state.get("enable_free_letters", True)
+    if free_letters_enabled and state["free_letters_used"] < MAX_FREE_LETTERS:
         state["last_action"] = f"Please choose {MAX_FREE_LETTERS - state['free_letters_used']} more free letter(s) first."
         return build_ui_outputs(state)
 
@@ -809,6 +898,14 @@ def build_guess_outputs(state: Dict[str, Any], audio_html: str = "", clear_input
     grid_button_updates = get_all_button_updates(state)
     letter_button_updates = get_letter_button_updates(state)
 
+    # Show share button only when game is over AND show_challenge_links is enabled
+    show_share = state.get("game_over", False) and state.get("show_challenge_links", True)
+    share_btn_visible = gr.Button(visible=show_share)
+
+    # Show free letter section only if enabled
+    show_free_letters = state.get("enable_free_letters", True)
+    free_letter_row_visible = gr.Row(visible=show_free_letters)
+
     return (
         *grid_button_updates,  # 48 grid button updates
         *letter_button_updates,  # 26 letter button updates
@@ -817,7 +914,9 @@ def build_guess_outputs(state: Dict[str, Any], audio_html: str = "", clear_input
         "" if clear_input else gr.update(),  # guess input - clear or no change
         audio_html,
         render_game_over_html(state),
-        render_free_letters_status(state),
+        render_free_letters_status(state) if show_free_letters else "",
+        free_letter_row_visible,
+        share_btn_visible,
         state
     )
 
@@ -865,16 +964,20 @@ def handle_guess(guess_text: str, state: Dict[str, Any]) -> tuple:
 
 def handle_new_game(
     wordlist: str,
+    ai_topic: str,
     game_mode: str,
     sfx_enabled: bool,
     sfx_volume: int,
     music_enabled: bool,
     music_volume: int,
+    show_incorrect: bool,
+    enable_free: bool,
+    show_challenge: bool,
     state: Dict[str, Any]
 ) -> tuple:
     """Handle new game creation."""
     state = ensure_state(state)
-    new_state = create_new_game_state(wordlist=wordlist, game_mode=game_mode)
+    new_state = create_new_game_state(wordlist=wordlist, game_mode=game_mode, ai_topic=ai_topic)
 
     # Preserve audio settings from UI components
     new_state["sound_effects_enabled"] = sfx_enabled
@@ -882,6 +985,15 @@ def handle_new_game(
     new_state["music_enabled"] = music_enabled
     new_state["music_volume"] = music_volume
 
+    # Preserve display settings from UI components
+    new_state["show_incorrect_guesses"] = show_incorrect
+    new_state["enable_free_letters"] = enable_free
+    new_state["show_challenge_links"] = show_challenge
+
+    # Update welcome message based on free letters setting
+    if not enable_free:
+        new_state["last_action"] = "Free letters disabled. Click grid cells to reveal letters!"
+
     return build_ui_outputs(new_state)
 
 
@@ -904,6 +1016,86 @@ def handle_audio_settings_change(
     return new_state
 
 
+def handle_share_challenge(
+    username: str,
+    state: Dict[str, Any]
+) -> Tuple[str, str, Dict[str, Any]]:
+    """Handle share challenge button click."""
+    state = ensure_state(state)
+
+    if not state.get("game_over"):
+        return "Game not finished yet.", "", state
+
+    username = username.strip() if username else "Anonymous"
+    if not username:
+        username = "Anonymous"
+
+    # Get game data
+    word_list = [text for text, x, y, direction in state["puzzle_words"]]
+    wordlist_source = state.get("wordlist", "classic.txt")
+    game_mode = state.get("game_mode", "classic")
+    score = state.get("score", 0)
+
+    # Calculate elapsed time
+    start_time = state.get("start_time")
+    end_time = state.get("end_time")
+    if end_time and start_time:
+        start = datetime.fromisoformat(start_time)
+        end = datetime.fromisoformat(end_time)
+        elapsed_seconds = int((end - start).total_seconds())
+    else:
+        elapsed_seconds = 0
+
+    # Check if this is a shared challenge being completed
+    is_shared_game = state.get("challenge_sid") is not None
+    existing_sid = state.get("challenge_sid")
+
+    try:
+        if is_shared_game and existing_sid:
+            # Add result to existing challenge
+            success = add_user_result_to_game(
+                sid=existing_sid,
+                username=username,
+                word_list=word_list,
+                score=score,
+                time_seconds=elapsed_seconds
+            )
+
+            if success:
+                share_url = get_shareable_url(existing_sid)
+                new_state = copy.deepcopy(state)
+                new_state["share_url"] = share_url
+                new_state["share_sid"] = existing_sid
+                return f"Result submitted for {username}!", share_url, new_state
+            else:
+                return "Failed to submit result.", "", state
+        else:
+            # Create new challenge
+            challenge_id, full_url, sid = save_game_to_hf(
+                word_list=word_list,
+                username=username,
+                score=score,
+                time_seconds=elapsed_seconds,
+                game_mode=game_mode,
+                grid_size=6,  # Wrdler: 6 rows
+                spacer=0,
+                may_overlap=False,
+                wordlist_source=wordlist_source
+            )
+
+            if sid:
+                share_url = get_shareable_url(sid)
+                new_state = copy.deepcopy(state)
+                new_state["share_url"] = share_url
+                new_state["share_sid"] = sid
+                return f"Share link generated!", share_url, new_state
+            else:
+                return "Failed to generate share link.", "", state
+
+    except Exception as e:
+        return f"Error: {str(e)}", "", state
+
+
 # ---------------------------------------------------------------------------
 # Main App Creation
 # ---------------------------------------------------------------------------
@@ -916,11 +1108,18 @@ def create_app() -> gr.Blocks:
     if not wordlist_files:
         wordlist_files = ["classic.txt"]
 
-    # CSS file path
+    # Load CSS content from file
     css_path = os.path.join(os.path.dirname(os.path.dirname(__file__)), "style_wrdler.css")
+    css_content = None
+    if os.path.exists(css_path):
+        try:
+            with open(css_path, "r", encoding="utf-8") as f:
+                css_content = f.read()
+        except Exception:
+            css_content = None
 
     with gr.Blocks(
-        css=css_path if os.path.exists(css_path) else None,
+        css=css_content,
         theme="Surn/beeuty",
         title=f"Wrdler v{__version__}"
     ) as demo:
@@ -933,37 +1132,54 @@ def create_app() -> gr.Blocks:
         gr.Markdown("Find all 6 hidden words in the 8×6 grid!")
 
         # Tab layout
-        with gr.Tabs():
+        with gr.Tabs():            
             # Game Tab
             with gr.TabItem("Game"):
                 with gr.Row():
-                    # Left column - Game area
-                    with gr.Column(scale=5):
+                    with gr.Column():
+                        # Topic input at top - styled as a prominent glowing badge
+                        # Get initial topic value
+                        initial_topic = wordlist_files[0].replace(".txt", "") if wordlist_files else "classic"
+                        topic_display = gr.Textbox(
+                            value=initial_topic,
+                            placeholder="Enter topic...",
+                            show_label=False,
+                            max_lines=1,
+                            lines=1,
+                            elem_id="topic-display",
+                            elem_classes=["topic-input"],
+                            interactive=True
+                        )
+
                         # Challenge mode leaderboard (if in challenge mode)
                         challenge_leaderboard_html = gr.HTML(
                             value="",
                             elem_id="challenge-leaderboard-container"
                         )
-
-                        # Free letter selection using button grid
-                        free_letter_status = gr.Markdown(
-                            value="Choose 2 free letters:",
-                            elem_id="free-letter-status"
-                        )
-                        # Create 26 letter buttons (only puzzle letters will be visible)
-                        letter_buttons: List[gr.Button] = []
-                        with gr.Row(elem_classes=["letter-buttons-row"]):
-                            for letter in ALL_LETTERS:
-                                btn = gr.Button(
-                                    value=letter,
-                                    variant="primary",
-                                    size="sm",
-                                    min_width=36,
-                                    visible=False,  # Will be shown for letters in puzzle
-                                    elem_classes=["letter-btn-available"],
-                                    elem_id=f"letter-{letter}"
+                with gr.Row():
+                    # Left column - Game area
+                    with gr.Column(scale=5):
+                        # Free letter selection using button grid (wrapped in Row for visibility control)
+                        with gr.Row(elem_classes=["free-letter-section"], visible=True) as free_letter_row:
+                            with gr.Column():
+                                free_letter_status = gr.Markdown(
+                                    value="Choose 2 free letters:",
+                                    elem_id="free-letter-status"
                                 )
-                                letter_buttons.append(btn)
+                                # Create letter buttons (only puzzle letters will be visible)
+                                letter_buttons: List[gr.Button] = []
+                                with gr.Row(elem_classes=["letter-buttons-row"]):
+                                    for letter in ALL_LETTERS:
+                                        btn = gr.Button(
+                                            value=letter,
+                                            variant="primary",
+                                            size="sm",
+                                            min_width=36,
+                                            visible=False,  # Will be shown for letters in puzzle
+                                            elem_classes=["letter-btn-available"],
+                                            elem_id=f"letter-{letter}"
+                                        )
+                                        letter_buttons.append(btn)
 
                         # Game grid using native Gradio buttons
                         # Create 48 buttons (6 rows x 8 cols) in a CSS grid
@@ -976,7 +1192,7 @@ def create_app() -> gr.Blocks:
                                             value="?",
                                             variant="primary",
                                             size="sm",
-                                            min_width=50,
+                                            min_width=20,
                                             elem_classes=["grid-cell-unrevealed"],
                                             elem_id=f"cell-{row}-{col}"
                                         )
@@ -984,45 +1200,86 @@ def create_app() -> gr.Blocks:
 
                         # Guess form
                         with gr.Row():
-                            guess_input = gr.Textbox(
-                                label="Your Guess",
-                                placeholder="Enter a word...",
-                                max_lines=1,
-                                elem_id="guess-input"
-                            )
-                            guess_btn = gr.Button("Guess", variant="primary", elem_id="guess-btn")
+                            # New Game button
+                            new_game_btn = gr.Button("New Game", variant="primary", size="lg")
+
 
                         # Status message
-                        status_msg = gr.Markdown(value="Welcome! Choose your 2 free letters to start.")
+                        status_msg = gr.Markdown(value="Welcome!")
 
                         # Game over display
                         game_over_html = gr.HTML(value="", elem_id="game-over-container")
 
+                        # Share Challenge Button (visible after game over)
+                        share_challenge_btn = gr.Button(
+                            "🎮 Share Your Challenge",
+                            variant="primary",
+                            visible=False,
+                            elem_id="share-challenge-btn",
+                            elem_classes=["share-challenge-trigger"]
+                        )
+
                     # Right column - Score panel and New Game
                     with gr.Column(scale=3):
+                        guess_input = gr.Textbox(
+                            label="Your Guess",
+                            placeholder="Enter a word...",
+                            max_lines=1,
+                            elem_id="guess-input"
+                        )
+                        guess_btn = gr.Button("Guess", variant="primary", elem_id="guess-btn")
                         # Score panel
                         score_panel_html = gr.HTML(
                             value=lambda: render_score_panel_html(create_new_game_state()),
                             elem_id="score-panel-container"
                         )
-                        # New Game button
-                        new_game_btn = gr.Button("New Game", variant="primary", size="lg")
+
+
 
             # Settings Tab
             with gr.TabItem("Settings"):
                 with gr.Row():
                     with gr.Column():
                         gr.Markdown("### Game Settings")
+                        # Add "AI Generated" option to wordlist choices
+                        wordlist_choices = ["AI Generated"] + wordlist_files
                         wordlist_dropdown = gr.Dropdown(
-                            choices=wordlist_files,
+                            choices=wordlist_choices,
                             value=wordlist_files[0] if wordlist_files else "classic.txt",
                             label="Word List"
                         )
+                        # AI Topic textbox and submit button (visible only when AI Generated is selected)
+                        with gr.Row(visible=False) as ai_topic_row:
+                            ai_topic_input = gr.Textbox(
+                                label="AI Topic",
+                                placeholder="Enter a topic (e.g., Ocean Life, Space, Cooking)",
+                                value="",
+                                scale=3,
+                                elem_id="ai-topic-input"
+                            )
+                            ai_topic_submit = gr.Button(
+                                "Generate",
+                                variant="primary",
+                                scale=1,
+                                elem_id="ai-topic-submit"
+                            )
                         game_mode_dropdown = gr.Dropdown(
                             choices=["classic", "easy", "too easy"],
                             value="classic",
                             label="Game Mode"
                         )
+                        show_incorrect_guesses = gr.Checkbox(
+                            value=True,
+                            label="Show Incorrect Guesses"
+                        )
+                        enable_free_letters = gr.Checkbox(
+                            value=True,
+                            label="Enable Free Letters"
+                        )
+                        show_challenge_links = gr.Checkbox(
+                            value=True,
+                            label="Show Challenge Share Links"
+                        )
 
                     with gr.Column():
                         gr.Markdown("### Audio Settings")
@@ -1052,8 +1309,32 @@ def create_app() -> gr.Blocks:
         # Hidden audio player for sound effects
         audio_player_html = gr.HTML(value="", elem_id="audio-player", visible=False)
 
+        # Timer for updating elapsed time (ticks every second)
+        game_timer = gr.Timer(value=1, active=True)
+
+        # Share Challenge Modal Dialog (outside tabs)
+        with Modal(visible=False) as share_modal:
+            gr.Markdown("## 🎮 Share Your Challenge")
+            gr.Markdown("Challenge your friends to beat your score!")
+            username_input = gr.Textbox(
+                label="Your Name (optional)",
+                placeholder="Anonymous",
+                max_lines=1,
+                elem_id="username-input"
+            )
+            share_btn = gr.Button("Generate Share Link", variant="primary", size="lg")
+            share_status = gr.Markdown(value="", elem_id="share-status")
+            share_url_display = gr.Textbox(
+                label="Share URL (click to copy)",
+                value="",
+                interactive=False,
+                visible=False,
+                elem_id="share-url-display"
+            )
+            close_modal_btn = gr.Button("Close", variant="secondary")
+
         # Define common outputs for handlers
-        # Order: 48 grid buttons, 26 letter buttons, score_panel, status_msg, audio, game_over, free_letter_status, state
+        # Order: 48 grid buttons, 26 letter buttons, score_panel, status_msg, audio, game_over, free_letter_status, free_letter_row, share_btn_visible, state
         common_outputs = [
             *grid_buttons,
             *letter_buttons,
@@ -1062,6 +1343,8 @@ def create_app() -> gr.Blocks:
             audio_player_html,
             game_over_html,
             free_letter_status,
+            free_letter_row,
+            share_challenge_btn,
             game_state
         ]
 
@@ -1075,6 +1358,8 @@ def create_app() -> gr.Blocks:
             audio_player_html,
             game_over_html,
             free_letter_status,
+            free_letter_row,
+            share_challenge_btn,
             game_state
         ]
 
@@ -1110,11 +1395,131 @@ def create_app() -> gr.Blocks:
             outputs=guess_outputs
         )
 
+        # Helper to get topic display value
+        def get_topic_display_value(wordlist, ai_topic):
+            """Get the display value for the topic textbox."""
+            if wordlist == "AI Generated" and ai_topic.strip():
+                return ai_topic.strip()
+            else:
+                return wordlist.replace(".txt", "") if wordlist else "classic"
+
         # New game button
         new_game_btn.click(
             fn=handle_new_game,
-            inputs=[wordlist_dropdown, game_mode_dropdown, sfx_enabled, sfx_volume, music_enabled, music_volume, game_state],
+            inputs=[wordlist_dropdown, ai_topic_input, game_mode_dropdown, sfx_enabled, sfx_volume, music_enabled, music_volume, show_incorrect_guesses, enable_free_letters, show_challenge_links, game_state],
+            outputs=common_outputs
+        ).then(
+            fn=lambda: gr.Timer(active=True),
+            inputs=None,
+            outputs=game_timer
+        ).then(
+            fn=get_topic_display_value,
+            inputs=[wordlist_dropdown, ai_topic_input],
+            outputs=topic_display
+        )
+
+        # Wordlist dropdown change handler - show/hide AI topic input row and update topic display
+        def handle_wordlist_change(wordlist, ai_topic):
+            """Show AI topic input when AI Generated is selected and update topic display."""
+            is_ai = wordlist == "AI Generated"
+            topic_value = ai_topic.strip() if is_ai and ai_topic.strip() else wordlist.replace(".txt", "")
+            return gr.Row(visible=is_ai), gr.Textbox(value=topic_value)
+
+        wordlist_dropdown.change(
+            fn=handle_wordlist_change,
+            inputs=[wordlist_dropdown, ai_topic_input],
+            outputs=[ai_topic_row, topic_display]
+        )
+
+        # AI Topic submit button - generates new game with AI words
+        ai_topic_submit.click(
+            fn=handle_new_game,
+            inputs=[wordlist_dropdown, ai_topic_input, game_mode_dropdown, sfx_enabled, sfx_volume, music_enabled, music_volume, show_incorrect_guesses, enable_free_letters, show_challenge_links, game_state],
             outputs=common_outputs
+        ).then(
+            fn=lambda: gr.Timer(active=True),
+            inputs=None,
+            outputs=game_timer
+        ).then(
+            fn=lambda topic: topic.strip() if topic.strip() else "AI Generated",
+            inputs=[ai_topic_input],
+            outputs=topic_display
+        )
+
+        # AI Topic textbox submit (pressing Enter)
+        ai_topic_input.submit(
+            fn=handle_new_game,
+            inputs=[wordlist_dropdown, ai_topic_input, game_mode_dropdown, sfx_enabled, sfx_volume, music_enabled, music_volume, show_incorrect_guesses, enable_free_letters, show_challenge_links, game_state],
+            outputs=common_outputs
+        ).then(
+            fn=lambda: gr.Timer(active=True),
+            inputs=None,
+            outputs=game_timer
+        ).then(
+            fn=lambda topic: topic.strip() if topic.strip() else "AI Generated",
+            inputs=[ai_topic_input],
+            outputs=topic_display
+        )
+
+        # Topic display submit handler - check if matches wordlist or use as AI topic
+        def handle_topic_submit(topic_input, game_mode, sfx_en, sfx_vol, music_en, music_vol, show_inc, enable_fl, show_chal, state):
+            """Handle topic input - match wordlist or use as AI topic."""
+            state = ensure_state(state)
+            topic_input = topic_input.strip()
+
+            # Check if input matches a wordlist file (with or without .txt)
+            matched_wordlist = None
+            for wf in wordlist_files:
+                name_without_ext = wf.replace(".txt", "")
+                if topic_input.lower() == wf.lower() or topic_input.lower() == name_without_ext.lower():
+                    matched_wordlist = wf
+                    break
+
+            if matched_wordlist:
+                # Use existing wordlist
+                new_state = create_new_game_state(wordlist=matched_wordlist, game_mode=game_mode, ai_topic="")
+                wordlist_value = matched_wordlist
+                ai_topic_value = ""
+                ai_row_visible = False
+            else:
+                # Use as AI topic
+                new_state = create_new_game_state(wordlist="AI Generated", game_mode=game_mode, ai_topic=topic_input)
+                wordlist_value = "AI Generated"
+                ai_topic_value = topic_input
+                ai_row_visible = True
+
+            # Preserve settings
+            new_state["sound_effects_enabled"] = sfx_en
+            new_state["sound_effects_volume"] = sfx_vol
+            new_state["music_enabled"] = music_en
+            new_state["music_volume"] = music_vol
+            new_state["show_incorrect_guesses"] = show_inc
+            new_state["enable_free_letters"] = enable_fl
+            new_state["show_challenge_links"] = show_chal
+
+            if not enable_fl:
+                new_state["last_action"] = "Free letters disabled. Click grid cells to reveal letters!"
+
+            # Build outputs + settings updates
+            base_outputs = build_ui_outputs(new_state)
+            return (
+                *base_outputs,
+                gr.Dropdown(value=wordlist_value),  # wordlist_dropdown
+                gr.Textbox(value=ai_topic_value),   # ai_topic_input
+                gr.Row(visible=ai_row_visible),     # ai_topic_row
+            )
+
+        # Extended outputs for topic submit (includes settings updates)
+        topic_submit_outputs = common_outputs + [wordlist_dropdown, ai_topic_input, ai_topic_row]
+
+        topic_display.submit(
+            fn=handle_topic_submit,
+            inputs=[topic_display, game_mode_dropdown, sfx_enabled, sfx_volume, music_enabled, music_volume, show_incorrect_guesses, enable_free_letters, show_challenge_links, game_state],
+            outputs=topic_submit_outputs
+        ).then(
+            fn=lambda: gr.Timer(active=True),
+            inputs=None,
+            outputs=game_timer
         )
 
         # Audio settings change handlers
@@ -1139,6 +1544,96 @@ def create_app() -> gr.Blocks:
             outputs=[game_state]
         )
 
+        # Show incorrect guesses toggle handler
+        def handle_show_incorrect_change(show_incorrect, state):
+            state = ensure_state(state)
+            new_state = copy.deepcopy(state)
+            new_state["show_incorrect_guesses"] = show_incorrect
+            return new_state
+
+        show_incorrect_guesses.change(
+            fn=handle_show_incorrect_change,
+            inputs=[show_incorrect_guesses, game_state],
+            outputs=[game_state]
+        )
+
+        # Enable free letters toggle handler
+        def handle_enable_free_letters_change(enabled, state):
+            state = ensure_state(state)
+            new_state = copy.deepcopy(state)
+            new_state["enable_free_letters"] = enabled
+            # Update message based on setting
+            if not enabled:
+                new_state["last_action"] = "Free letters disabled. Click grid cells to reveal letters!"
+            elif new_state.get("free_letters_used", 0) < MAX_FREE_LETTERS:
+                remaining = MAX_FREE_LETTERS - new_state.get("free_letters_used", 0)
+                new_state["last_action"] = f"Choose {remaining} free letter{'s' if remaining > 1 else ''} to start."
+            return build_ui_outputs(new_state)
+
+        enable_free_letters.change(
+            fn=handle_enable_free_letters_change,
+            inputs=[enable_free_letters, game_state],
+            outputs=common_outputs
+        )
+
+        # Show challenge links toggle handler
+        def handle_show_challenge_links_change(enabled, state):
+            state = ensure_state(state)
+            new_state = copy.deepcopy(state)
+            new_state["show_challenge_links"] = enabled
+            return build_ui_outputs(new_state)
+
+        show_challenge_links.change(
+            fn=handle_show_challenge_links_change,
+            inputs=[show_challenge_links, game_state],
+            outputs=common_outputs
+        )
+
+        # Share challenge button handler
+        def on_share_click(username, state):
+            """Handle share button click."""
+            status_text, url, new_state = handle_share_challenge(username, state)
+            url_visible = bool(url)
+            return (
+                status_text,
+                gr.Textbox(value=url, visible=url_visible),
+                new_state
+            )
+
+        share_btn.click(
+            fn=on_share_click,
+            inputs=[username_input, game_state],
+            outputs=[share_status, share_url_display, game_state]
+        )
+
+        # Modal open/close handlers
+        share_challenge_btn.click(
+            fn=lambda: Modal(visible=True),
+            inputs=None,
+            outputs=share_modal
+        )
+
+        close_modal_btn.click(
+            fn=lambda: Modal(visible=False),
+            inputs=None,
+            outputs=share_modal
+        )
+
+        # Timer tick handler - updates score panel with current elapsed time
+        def handle_timer_tick(state):
+            """Update score panel on timer tick."""
+            state = ensure_state(state)
+            if state.get("game_over"):
+                # Stop updating when game is over
+                return render_score_panel_html(state), gr.Timer(active=False)
+            return render_score_panel_html(state), gr.Timer(active=True)
+
+        game_timer.tick(
+            fn=handle_timer_tick,
+            inputs=[game_state],
+            outputs=[score_panel_html, game_timer]
+        )
+
         # Initialize UI on app load
         def initialize_ui(state):
             """Initialize UI components on app load."""

wrdler/word_loader.py

@@ -3,11 +3,25 @@ from __future__ import annotations
 import re
 import os
 import string
+import logging
+from functools import lru_cache
 from typing import Dict, List, Optional
-
-import streamlit as st
 from importlib import resources
 
+# Configure logging
+logger = logging.getLogger(__name__)
+
+# Streamlit caching - only use if we're actually in a Streamlit runtime
+_USE_STREAMLIT_CACHE = False
+try:
+    import streamlit as st
+    from streamlit.runtime.scriptrunner import get_script_run_ctx
+    # Check if we're actually in a Streamlit runtime
+    if get_script_run_ctx() is not None:
+        _USE_STREAMLIT_CACHE = True
+except Exception:
+    pass
+
 
 # Minimal built-ins used if the external file is missing or too small
 FALLBACK_WORDS: Dict[int, List[str]] = {
@@ -33,7 +47,15 @@ def get_wordlist_files() -> list[str]:
     return sorted(files)
 
 
-@st.cache_data(show_spinner=False)
+def _cache_decorator(func):
+    """Apply appropriate caching based on runtime environment."""
+    if _USE_STREAMLIT_CACHE:
+        return st.cache_data(show_spinner=False)(func)
+    else:
+        return lru_cache(maxsize=32)(func)
+
+
+@_cache_decorator
 def load_word_list(selected_file: Optional[str] = None) -> Dict[int, List[str]]:
     """
     Load a word list, filter to uppercase A–Z, lengths in {4,5,6}, and dedupe while preserving order.
@@ -389,7 +411,7 @@ def compute_word_difficulties(file_path, words_array=None):
     return total_difficulty, difficulties
 
 
-@st.cache_data(show_spinner=False)
+@_cache_decorator
 def load_word_list_or_ai(
     use_ai: bool = False,
     topic: str = "English",

wrdler/word_loader_ai.py

@@ -6,16 +6,23 @@ import re
 import string
 import logging
 from datetime import datetime
+from functools import lru_cache
 from typing import Dict, List, Optional, Tuple
 
 # Configure logging
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
 
-# Streamlit is optional; degrade gracefully if absent
+# Streamlit caching - only use if we're actually in a Streamlit runtime
+_USE_STREAMLIT_CACHE = False
 try:
     import streamlit as st
+    from streamlit.runtime.scriptrunner import get_script_run_ctx
+    # Check if we're actually in a Streamlit runtime
+    if get_script_run_ctx() is not None:
+        _USE_STREAMLIT_CACHE = True
 except Exception:  # pragma: no cover
+    # Create stub for when streamlit isn't installed
     class _Stub:
         def cache_resource(self, **_):  # type: ignore
             def deco(fn):
@@ -127,7 +134,15 @@ def _generate_via_hf_space(topic: str) -> Tuple[str, str]:
 # Model Loading
 # ---------------------------------------------------------------------------
 
-@st.cache_resource(show_spinner=False)
+def _resource_cache_decorator(func):
+    """Apply appropriate caching for resource loading based on runtime environment."""
+    if _USE_STREAMLIT_CACHE:
+        return st.cache_resource(show_spinner=False)(func)
+    else:
+        return lru_cache(maxsize=4)(func)
+
+
+@_resource_cache_decorator
 def _load_model(model_name: str = DEFAULT_MODEL_NAME):
     """
     Try to load the requested model first, then fall back through AI_MODELS in order.

wrdler/words/cooking.txt

@@ -1,24 +1,35 @@
 # AI-generated word list
-# Topic: COOKing
-# Last updated: 2025-11-28 12:16:45
-# Total words: 174
+# Topic: Cooking
+# Last updated: 2025-11-29 15:33:26
+# Total words: 270
 # Format: one word per line, sorted by length then alphabetically
 #
 BAKE
+BEAN
 BEEN
 BLUE
 BOIL
+BOWE
+BUCK
 BUFF
 CAKE
 CALV
 CARD
+CHOP
 COOK
+CUBE
+CURE
+DASH
+DINE
+EGGS
+EGGY
 FARM
 FAST
 FILL
 FIRE
 FISH
 FIZZ
+FOIL
 FOOD
 FRYD
 HARV
@@ -27,75 +38,121 @@ JUST
 KEEN
 KERN
 KING
+KITT
+LICK
 MAKE
 MANU
 MASH
 MEAT
+MEGA
 MINI
+OVEN
+PANE
+PEEK
+PEEL
 PICK
 PLAN
+PLUM
 POTS
 POUR
 PREP
 PUFF
 RACK
+RAWY
 RECT
+RIPE
 ROLL
 SEAR
 SEEK
+SHAK
 SIFT
 SIMP
 SKIL
 SKIP
 SLOW
+SMOK
 SOFT
 SOUP
 STEW
 STIR
+STOV
 TAKE
+TART
+TASI
 THAW
+TRIM
+TUBE
 TURK
 VEAL
+VINE
 WARM
 WASH
+WELD
 WELL
 WHIP
 WRAP
+ZOOM
 BACON
 BAKED
 BASTE
+BATCH
+BERRY
+BESTE
+BEVAP
+BITCH
+BLACK
 BLANK
 BLEND
 BLTIG
 BOATS
 BOILD
 BREAD
+BREAK
+BRINE
 BROWN
 BUTTI
+CANDS
 CANDY
 CARBS
 CHICK
 CHILL
+CHOPS
+CHUTE
 CLEAN
+CRACK
 CRUMB
 CRUST
+DINER
 DRIED
 FLAKY
+FRICK
 FRIED
 FRUIT
+FRYED
 FRYER
+GAMES
 GLAZE
 GRAIN
 GRASS
 GRILL
+GRIME
+GUESS
 HARVE
 HERBS
 HOUSE
+JELLY
+JUICE
 KITCH
 KNEAD
+KNIFE
 MARIN
+METAL
 MIXED
 MIXER
+OVENS
+OVENY
+PANDA
+PANGS
 PASTA
 PLATE
 PREPS
@@ -107,19 +164,29 @@ SALAD
 SALTY
 SAUTE
 SCONE
+SCRAP
+SHARP
 SHAVE
 SHRIL
 SLICE
 SLICK
 SMAKE
+SMALL
+SMOKE
+SNACK
+SPECK
 SPICE
 SPICY
 SPIRE
+SPLAT
 START
 STEAK
+STEAM
 STICK
 STIRD
 STIRP
+STIRR
+STOCK
 STOVE
 SWEET
 TASTE
@@ -136,45 +203,74 @@ WHISK
 WIELD
 YIELD
 ZESTY
+AROMAS
 ASSERT
+BAKERY
+BAKING
 BARELY
 BARKED
 BAROBA
 BATTER
 BAUGHT
 BAZAAR
+BITOUT
 BITTER
 BOILED
+BREADS
 BROWNY
+BUCKET
 CARROT
 CHEESE
+CHEFES
 COOKED
 COOKER
 COOKIN
 DETAIL
 DILUTE
+DINING
 EATING
+FLAVOR
 FLOURD
 FLYING
 FROZEN
+FRYING
+FRYOUT
 GRATED
 GRILLD
+KITTEN
 KNEADD
+LIQUID
 LITTLE
 MARINA
 MASHED
 METHOD
+MIXOUT
 MUFFIN
 NOODLE
+OVENED
+OVENER
 PACKED
+PANELS
 PICKED
+PICKLE
 PIERCE
 RECIPE
+REMAIN
+REPEAT
+SALAMI
+SALTED
+SEASON
 SHIELD
 SMELLY
 SMOOTH
 SNAKES
 SPICED
+SPICES
+SPLEND
+STOVEL
 TASTES
+THAWED
+TOMATO
 TOUCHS
 VEGGIE
+WRIGHT