Spaces:

MCP-1st-Birthday
/

wrdler

Running

App Files Files Community

wrdler / README.md

Surn

Enhance game UI and settings management

e008df8 8 days ago

preview code

raw

history blame

29.7 kB

metadata

title: Wrdler
emoji: 🎲
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.50.0
python_version: 3.12.8
app_port: 8501
app_file: app.py
suggested_hardware: cpu-basic
pinned: false
tags:
  - game
  - vocabulary
  - streamlit
  - gradio
  - education
  - ai
short_description: Fast paced word guessing game with AI-generated word lists
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/6346595c9e5f0fe83fc60444/6rWS4AIaozoNMCbx9F5Rv.png

Wrdler

This project is based on BattleWords, but adapted for a simpler word puzzle game with an 8x6 grid, horizontal words only, and free letter guesses at the start.

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

Key Differences from BattleWords

8x6 grid (instead of 12x12) with 6 words total (one per row)
Horizontal words only (no vertical placement)
No scope/radar visualization
2 free letter guesses at the start - choose letters to reveal all instances in the grid

Features

Core Gameplay

8x6 grid with six hidden words (one per row, all horizontal)
Word composition: Each puzzle contains exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
Game starts with 2 free letter guesses; all instances of chosen letters are revealed
Reveal grid cells and guess words for points
Scoring tiers: Good (34–37), Great (38–41), Fantastic (42+)
Game ends when all words are guessed or all word letters are revealed
Incorrect guess history with tooltip and optional display (enabled by default)
10 incorrect guess limit per game
Two game modes: Classic (chain guesses) and Too Easy (single guess per reveal)

Audio & Visuals

Ocean-themed gradient background with wave animations
Background music system (toggleable with volume control)
Sound effects for hits, misses, correct/incorrect guesses
Responsive UI built with Streamlit

AI Word Generation

Topic-based word lists: Generate custom word lists using AI for any theme
Intelligent word expansion: New AI-generated words automatically saved to local files
- Smart detection separates existing dictionary words from new AI words
- Only saves new words to prevent duplicates
- Automatic retry mechanism (up to 3 attempts) for insufficient word counts
- 1000-word file size limit prevents bloat
- Auto-sorted by length then alphabetically
Dual generation modes:
- HF Space API (primary): Uses Hugging Face Space when USE_HF_WORDS=true
- Local transformers (fallback): Falls back to local models if HF unavailable
Fallback support: Gracefully uses dictionary words if AI generation fails
Guaranteed distribution: Ensures exactly 25 words each of lengths 4, 5, and 6

Customization

Multiple word lists (classic, fourth_grade, wordlist)
Wordlist sidebar controls (picker + one-click sort)
Audio volume controls (music and effects separate)

✅ Challenge Mode

Shareable challenge links via short URLs (?game_id=<sid>)
Multi-user leaderboards sorted by score and time
Remote storage via Hugging Face datasets
Word list difficulty calculation and display
Submit results to existing challenges or create new ones
Top 5 leaderboard display in Challenge Mode banner
"Show Challenge Share Links" toggle (default OFF) to control URL visibility
Each player gets different random words from the same wordlist

Deployment & Technical

Dockerfile-based deployment supported for Hugging Face Spaces and other container platforms
Dual UI frameworks:
- Streamlit 1.51.0 (default) - Feature-rich, session-state based
- Gradio 5.50+ (alternative) - Modern, reactive components
- Reference: Gradio 6 Migration Guide
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

Clone the repository:

git clone https://github.com/Oncorporation/Wrdler.git
cd wrdler

(Optional) Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate # On Windows use `venv\Scripts\activate`

Install dependencies: ( add --system if not using a virutal environment)

uv pip install -r requirements.txt --link-mode=copy

Running Wrdler

You can run the app locally using either uv or Streamlit directly:

Streamlit UI (default):

uv run streamlit run app.py
# or
streamlit run app.py

Gradio UI (alternative):

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 or any Docker-compatible environment.

To deploy on Hugging Face Spaces:

Add a Dockerfile to your repository root (see Spaces Dockerfile guide).
Push your code to your Hugging Face Space.
The platform will build and run your app automatically.

For local Docker runs:

docker build -t wrdler .
docker run -p8501:8501 wrdler

Environment Variables (for Challenge Mode)

Challenge Mode requires a .env file in the project root with HuggingFace Hub credentials:

# Required for Challenge Mode
HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx  # or HF_TOKEN
HF_REPO_ID=YourUsername/YourRepo       # Target HF dataset repo
SPACE_NAME=YourUsername/Wrdler         # Your HF Space name

# Optional
CRYPTO_PK=                             # Reserved for future signing

How to get your HF_API_TOKEN:

Go to https://huggingface.co/settings/tokens
Create a new token with write access
Add to .env file as HF_API_TOKEN=hf_...

Note: The app works without these variables, but Challenge Mode features (sharing, leaderboards) will be disabled.

Folder Structure

app.py – Streamlit entry point
wrdler/ – Python package
models.py – data models and types
word_loader.py – word list loading and validation
word_loader_ai.py – AI word generation with HF Space API and local transformers
generator.py – word placement logic (8x6, horizontal only)
logic.py – game mechanics (reveal, guess, scoring, free letters)
ui.py – Streamlit UI composition
gradio_ui.py – Gradio UI implementation (alternative interface)
game_storage.py – Hugging Face remote storage integration and challenge sharing
local_storage.py – local JSON storage for results and high scores
storage.py – (legacy) local storage and high scores
modules/ – shared utility modules (storage, constants, file_utils)
words/ – word list files (classic.txt, fourth_grade.txt, wordlist.txt, AI-generated)
style_wrdler.css – Custom CSS styling for Gradio interface
specs/ – documentation (specs.md, requirements.md)
tests/ – unit tests

Test File Location

All test files must be placed in the /tests folder. This ensures a clean project structure and makes it easy to discover and run all tests.

How to Play

Start with 2 free letter guesses - choose two letters to reveal all their instances in the grid.
Click grid squares to reveal letters or empty spaces.
After revealing a letter, enter a guess for a word in the text box.
Earn points for correct guesses and bonus points for unrevealed letters.
The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.
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

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
Custom styling via style_wrdler.css
State management with gr.State and deep copy updates
Event handlers use .click(), .change(), .submit() methods
Modal dialogs with gr.Modal(visible=False) pattern


# Response
````````markdown
---
title: Wrdler
emoji: 🎲
colorFrom: blue
colorTo: indigo
sdk: streamlit
sdk_version: 1.51.0
python_version: 3.12.8
app_port: 8501
app_file: app.py
suggested_hardware: cpu-basic
pinned: false
tags:
- game
- vocabulary
- streamlit
- gradio
- education
- ai
short_description: Fast paced word guessing game with AI-generated word lists
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/6346595c9e5f0fe83fc60444/6rWS4AIaozoNMCbx9F5Rv.png
---

# Wrdler

> **This project is based on BattleWords, but adapted for a simpler word puzzle game with an 8x6 grid, horizontal words only, and free letter guesses at the start.**

Wrdler is a vocabulary learning game with a simplified grid and strategic letter guessing. The objective is to discover hidden words on a grid by making smart guesses before all letters are revealed.

**Dual UI Support:** Play with Streamlit (default) or Gradio 5.50+ (alternative) - same great gameplay, your choice of framework!

**🎮 Live Demo:** [Play on Hugging Face Spaces](https://huggingface.co/spaces/Surn/Wrdler)

## Key Differences from BattleWords

- **8x6 grid** (instead of 12x12) with **6 words total** (one per row)
- **Horizontal words only** (no vertical placement)
- **No scope/radar visualization**
- **2 free letter guesses** at the start - choose letters to reveal all instances in the grid

## Features

### Core Gameplay
- 8x6 grid with six hidden words (one per row, all horizontal)
- **Word composition:** Each puzzle contains exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
- Game starts with 2 free letter guesses; all instances of chosen letters are revealed
- Reveal grid cells and guess words for points
- Scoring tiers: Good (34–37), Great (38–41), Fantastic (42+)
- Game ends when all words are guessed or all word letters are revealed
- Incorrect guess history with tooltip and optional display (enabled by default)
- 10 incorrect guess limit per game
- Two game modes: Classic (chain guesses) and Too Easy (single guess per reveal)

### Audio & Visuals
- Ocean-themed gradient background with wave animations
- Background music system (toggleable with volume control)
- Sound effects for hits, misses, correct/incorrect guesses
- Responsive UI built with Streamlit

### AI Word Generation
- **Topic-based word lists**: Generate custom word lists using AI for any theme
- **Intelligent word expansion**: New AI-generated words automatically saved to local files
  - Smart detection separates existing dictionary words from new AI words
  - Only saves new words to prevent duplicates
  - Automatic retry mechanism (up to 3 attempts) for insufficient word counts
  - 1000-word file size limit prevents bloat
  - Auto-sorted by length then alphabetically
- **Dual generation modes**:
  - **HF Space API** (primary): Uses Hugging Face Space when `USE_HF_WORDS=true`
  - **Local transformers** (fallback): Falls back to local models if HF unavailable
- **Fallback support**: Gracefully uses dictionary words if AI generation fails
- **Guaranteed distribution**: Ensures exactly 25 words each of lengths 4, 5, and 6

### Customization
- Multiple word lists (classic, fourth_grade, wordlist)
- Wordlist sidebar controls (picker + one-click sort)
- Audio volume controls (music and effects separate)

### ✅ Challenge Mode
- **Shareable challenge links** via short URLs (`?game_id=<sid>`)
- **Multi-user leaderboards** sorted by score and time
- **Remote storage** via Hugging Face datasets
- **Word list difficulty calculation** and display
- **Submit results** to existing challenges or create new ones
- **Top 5 leaderboard** display in Challenge Mode banner
- **"Show Challenge Share Links" toggle** (default OFF) to control URL visibility
- Each player gets different random words from the same wordlist

### Deployment & Technical
- **Dockerfile-based deployment** supported for Hugging Face Spaces and other container platforms
- **Dual UI frameworks**: 
  - **Streamlit 1.51.0** (default) - Feature-rich, session-state based
  - **Gradio 5.50+** (alternative) - Modern, reactive components
  - Reference: [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)
- **Environment variables** for Challenge Mode (HF_API_TOKEN, HF_REPO_ID, SPACE_NAME)
- Works offline without HF credentials (Challenge Mode features disabled gracefully)
- Compatible with both local development and cloud deployment

### Progressive Web App (PWA)
- Installable on desktop and mobile from your browser
- Includes `service worker` and `manifest.json` with basic offline caching of static assets
- See `INSTALL_GUIDE.md` for platform-specific steps

### Planned
- Local persistent storage for personal game history
- Personal high scores sidebar (offline-capable)
- Player statistics tracking
- Deterministic seed UI for custom puzzles

## Challenge Mode & Leaderboard

When playing a shared challenge (via a `game_id` link), the leaderboard displays all submitted results for that challenge. The leaderboard is **sorted by highest score (descending), then by fastest time (ascending)**. This means players with the most points appear at the top, and ties are broken by the shortest completion time.

## Installation
1. Clone the repository:
 ```
 git clone https://github.com/Oncorporation/Wrdler.git
 cd wrdler
 ```
2. (Optional) Create and activate a virtual environment:
 ```
 python -m venv venv
 source venv/bin/activate # On Windows use `venv\Scripts\activate`
 ```
3. Install dependencies: ( add --system if not using a virutal environment)
 ```
 uv pip install -r requirements.txt --link-mode=copy 
 ```


## Running Wrdler

You can run the app locally using either [uv](https://github.com/astral-sh/uv) or Streamlit directly:

**Streamlit UI (default):**
```bash
uv run streamlit run app.py
# or
streamlit run app.py
```

**Gradio UI (alternative):**
```bash
python -m wrdler.gradio_ui
# or run the Gradio demo file directly
```

Both interfaces provide the same gameplay experience with slightly different UI frameworks.

### Dockerfile Deployment (Hugging Face Spaces and more)

Wrdler supports containerized deployment using a `Dockerfile`. This is the recommended method for deploying to [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker) or any Docker-compatible environment.

To deploy on Hugging Face Spaces:
1. Add a `Dockerfile` to your repository root (see [Spaces Dockerfile guide](https://huggingface.co/docs/hub/spaces-sdks-docker)).
2. Push your code to your Hugging Face Space.
3. The platform will build and run your app automatically.

For local Docker runs:
```sh
docker build -t wrdler .
docker run -p8501:8501 wrdler
```

### Environment Variables (for Challenge Mode)

Challenge Mode requires a `.env` file in the project root with HuggingFace Hub credentials:

```bash
# Required for Challenge Mode
HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx  # or HF_TOKEN
HF_REPO_ID=YourUsername/YourRepo       # Target HF dataset repo
SPACE_NAME=YourUsername/Wrdler         # Your HF Space name

# Optional
CRYPTO_PK=                             # Reserved for future signing
```

**How to get your HF_API_TOKEN:**
1. Go to https://huggingface.co/settings/tokens
2. Create a new token with `write` access
3. Add to `.env` file as `HF_API_TOKEN=hf_...`

**Note:** The app works without these variables, but Challenge Mode features (sharing, leaderboards) will be disabled.

## Folder Structure

- `app.py` – Streamlit entry point
- `wrdler/` – Python package
 - `models.py` – data models and types
 - `word_loader.py` – word list loading and validation
 - `word_loader_ai.py` – AI word generation with HF Space API and local transformers
 - `generator.py` – word placement logic (8x6, horizontal only)
 - `logic.py` – game mechanics (reveal, guess, scoring, free letters)
 - `ui.py` – Streamlit UI composition
 - `gradio_ui.py` – Gradio UI implementation (alternative interface)
 - `game_storage.py` – Hugging Face remote storage integration and challenge sharing
 - `local_storage.py` – local JSON storage for results and high scores
 - `storage.py` – (legacy) local storage and high scores
 - `modules/` – shared utility modules (storage, constants, file_utils)
 - `words/` – word list files (classic.txt, fourth_grade.txt, wordlist.txt, AI-generated)
- `style_wrdler.css` – Custom CSS styling for Gradio interface
- `specs/` – documentation (`specs.md`, `requirements.md`)
- `tests/` – unit tests

## Test File Location
All test files must be placed in the `/tests` folder. This ensures a clean project structure and makes it easy to discover and run all tests.

## How to Play

1. **Start with 2 free letter guesses** - choose two letters to reveal all their instances in the grid.
2. Click grid squares to reveal letters or empty spaces.
3. After revealing a letter, enter a guess for a word in the text box.
4. Earn points for correct guesses and bonus points for unrevealed letters.
5. **The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.**
6. **To play a shared challenge, use a link with `?game_id=<sid>`. Your result will be added to the challenge leaderboard.**

## Changelog

### v0.1.2 (Current)
- ✅ **Gradio UI Topic Display** - Prominent neon-styled badge at top of game area
  - Glassmorphism background with glowing cyan border
  - Pulsing neon animation effect
  - Editable - type new topic and press Enter to generate/switch word lists
- ✅ **Settings Persistence** - Enable Free Letters and Show Challenge Links persist across new games
- ✅ **Timer Implementation** - Real-time game timer using gr.Timer component
- ✅ **AI Topic Generation UI** - Added to Settings tab with Generate button
- ✅ **Streamlit Cache Fix** - Conditional caching to avoid warnings in Gradio mode
- ✅ **Enhanced CSS Styling** - Improved grid container, topic display, and responsive design

### v0.1.1
- ✅ Enhanced AI word generation with intelligent word saving
- ✅ Automatic retry mechanism for insufficient word counts (up to 3 retries)
- ✅ 1000-word file size limit to prevent dictionary bloat
- ✅ Improved new word detection (separates existing vs. new words before saving)
- ✅ Better HF Space API integration with graceful fallback to local models
- ✅ Additional word generation when initial pass doesn't meet MIN_REQUIRED threshold
- ✅ Enhanced logging for word generation pipeline visibility
- ✅ **Gradio UI implementation** (gradio>=5.50) as alternative to Streamlit
- ✅ Custom CSS styling for Gradio interface (style_wrdler.css)
- ✅ Dual UI framework support - choose between Streamlit or Gradio

### v0.1.0
- ✅ AI word generation functionality added
- ✅ Topic-based custom word list creation
- ✅ Dual generation modes (HF Space API + local transformers)
- ✅ Utility modules integration (storage, file_utils, constants)
- ✅ Documentation synchronized across all files

### v0.0.8
 - remove background animation
 - add "easy" mode (single guess per reveal)

### v0.0.7 
 - fix guess bug - allowing guesses only after word guessed or letter revealed

### v0.0.2 (Current - All Sprints Complete) 🎉
 - **Sprint 1-3:** Core data models, generator refactor, radar removal
 - **Sprint 4:** Implemented free letter selection UI with circular green gradient buttons
 - **Sprint 5:** Updated grid UI rendering for 8×6 display
 - **Sprint 6:** Comprehensive integration testing (7/7 tests passing)
 - **Sprint 7:** Complete documentation update
 - Sound effects integration for free letter selection
 - Mobile-responsive free letter grid
 - Fixed duplicate rendering call bug
 - **All core Wrdler features complete and tested**

### v0.0.1 (Initial Wrdler Release)
 - Project renamed from BattleWords to Wrdler
 - Grid resized from 12x12 to 8x6
 - Changed to one word per row (6 total), horizontal only
 - Removed vertical word placement
 - Removed scope/radar visualization
 - Core data models updated for rectangular grid
 - Generator refactored for horizontal-only placement

Note
- `battlewords/storage.py` remains local-only storage; a separate HF integration wrapper is provided as `game_storage.py` for remote challenge mode.

## Known Issues / TODO

- Word list loading bug: the app may not select the proper word lists in some environments. Investigate `word_loader.get_wordlist_files()` / `load_word_list()` and sidebar selection to ensure the chosen file is correctly used by the generator.

## Development Phases

- **Proof of Concept (0.1.0):** No overlaps, basic UI, single session.
- **Beta (0.5.0):** Overlaps allowed on shared letters, responsive layout, keyboard support, deterministic seed.
- **Full (1.0.0):** Enhanced UX, persistence, leaderboards, daily/practice modes, advanced features.

See `specs/requirements.md` and `specs/specs.md` for full details and roadmap.

## License

Wrdler is based on BattleWords. BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.

## Hugging Face Spaces Configuration

Wrdler is deployable as a Hugging Face Space with **dual UI support**: Streamlit (default) and Gradio (>=5.50). You can use either the YAML config block or a Dockerfile for advanced/custom deployments.

To configure your Space with the YAML block, add it at the top of your `README.md`:

**Streamlit Configuration (default):**
```yaml
---
title: Wrdler
emoji: 🎲
colorFrom: blue
colorTo: indigo
sdk: streamlit
sdk_version: 1.51.0
python_version: 3.12.8
app_file: app.py
suggested_hardware: cpu-basic
tags:
 - game
 - vocabulary
 - streamlit
 - education
 - ai
---
```

**Gradio Configuration (alternative):**
```yaml
---
title: Wrdler Gradio
emoji: 🎲
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.50
python_version: 3.12.8
app_file: wrdler/gradio_ui.py
suggested_hardware: cpu-basic
tags:
 - game
 - vocabulary
 - gradio
 - education
 - ai
---
```

**Key parameters:**
- `title`, `emoji`, `colorFrom`, `colorTo`: Visuals for your Space.
- `sdk`: Use `streamlit` or `gradio` depending on your preferred UI framework.
- `sdk_version`: Latest supported version (Streamlit 1.51.0 or Gradio 5.50+).
- `python_version`: Python version (3.12.8 recommended).
- `app_file`: Entry point for your app (`app.py` for Streamlit, `wrdler/gradio_ui.py` for Gradio).
- `suggested_hardware`: Recommended hardware tier (cpu-basic is sufficient).
- `tags`: List of descriptive tags.

**Gradio Implementation Notes:**
- Uses modern Gradio 5.50+ API (compatible with upcoming Gradio 6)
- Reference: [Gradio 6 Migration Guide](https://www.gradio.app/guides/gradio-6-migration-guide)
- Custom styling via `style_wrdler.css`
- State management with `gr.State` and deep copy updates
- Event handlers use `.click()`, `.change()`, `.submit()` methods
- Modal dialogs with `gr.Modal(visible=False)` pattern