| # Wrdler - Project Context | |
| ## Project Overview | |
| Wrdler is a simplified vocabulary puzzle game based on BattleWords, with these key differences: | |
| - **8x6 grid** (instead of 12x12) | |
| - **One word per row, horizontal only** (no vertical words) | |
| - **No scope/radar visualization** | |
| - **2 free letter guesses at game start** (all instances of chosen letters are revealed) | |
| **Current Version:** 0.0.4 | |
| **Repository:** https://github.com/Oncorporation/Wrdler.git | |
| **Live Demo:** [DEPLOYMENT_URL_HERE] | |
| ## Recent Changes | |
| **v0.0.4 (Current):** | |
| - ✅ Version updated in `__init__.py` to 0.0.4 | |
| - ✅ Documentation synchronized across all files | |
| - ✅ Project structure validated and consistent | |
| - ✅ All Phase 1 requirements complete (7 sprints) | |
| - ✅ 100% test coverage (25/25 tests passing) | |
| - **Status: Ready for deployment!** 🚀 | |
| **v0.0.2-0.0.3 (Previous):** | |
| - ✅ All 7 sprints complete (12.75 hours development time) | |
| - ✅ Core data models updated for rectangular 8×6 grid | |
| - ✅ Generator refactored for horizontal-only, one-per-row placement | |
| - ✅ Radar/scope visualization removed (~217 lines) | |
| - ✅ Free letter selection UI with circular green gradient buttons | |
| - ✅ Grid UI updated for 8×6 display with responsive layout | |
| - ✅ Comprehensive integration testing suite | |
| - ✅ Complete documentation (GAMEPLAY_GUIDE.md) | |
| - ✅ Fixed duplicate rendering call bug | |
| - ✅ PWA support with service worker and manifest | |
| ## Core Gameplay | |
| - 8x6 grid with 6 hidden words (one per row, horizontal only) | |
| - **Word composition:** 2 four-letter words, 2 five-letter words, 2 six-letter words | |
| - No scope/radar visualization | |
| - Players start by choosing 2 letters; all instances are revealed | |
| - Players click cells to reveal letters or empty spaces | |
| - After revealing a letter, players can guess words | |
| - Scoring: word length + bonus for unrevealed letters | |
| - Game ends when all words are guessed or all word letters are revealed | |
| - Incorrect guess history with optional display (enabled by default) | |
| - 10 incorrect guess limit per game | |
| - **✅ IMPLEMENTED:** Challenge Mode with game sharing via short URLs | |
| - **✅ IMPLEMENTED:** Remote storage via Hugging Face datasets | |
| - **✅ IMPLEMENTED:** PWA install support (v0.2.28+) | |
| - **PLANNED:** Local persistent storage for game results and high scores (v0.3.0) | |
| ### Scoring Tiers | |
| - **Fantastic:** 42+ points | |
| - **Great:** 38-41 points | |
| - **Good:** 34-37 points | |
| - **Keep practicing:** < 34 points | |
| ## Technical Architecture | |
| ### Technology Stack | |
| - **Framework:** Streamlit 1.51.0 | |
| - **Language:** Python 3.12.8 (requires >=3.12, <3.13) | |
| - **Visualization:** Matplotlib (>=3.8) | |
| - **HTTP Requests:** requests (>=2.31.0) | |
| - **Remote Storage:** huggingface_hub (>=0.20.0) | |
| - **Environment:** python-dotenv (>=1.0.0) | |
| - **Testing:** Pytest | |
| - **Package Manager:** UV or pip | |
| ### Project Structure | |
| ``` | |
| wrdler/ | |
| ├── app.py # Streamlit entry point | |
| ├── wrdler/ # Main package | |
| │ ├── __init__.py # Version: 0.0.4 | |
| │ ├── 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 | |
| │ ├── word_loader.py # Word list management | |
| │ ├── audio.py # Background music system | |
| │ ├── sounds.py # Sound effects management | |
| │ ├── generate_sounds.py # Sound generation utilities | |
| │ ├── game_storage.py # HF game storage wrapper | |
| │ ├── version_info.py # Version display | |
| │ ├── modules/ # Shared utility modules (from OpenBadge) | |
| │ │ ├── __init__.py # Module exports | |
| │ │ ├── storage.py # HuggingFace storage & URL shortener | |
| │ │ ├── storage.md # Storage module documentation | |
| │ │ ├── constants.py # Storage-related constants (trimmed) | |
| │ │ └── file_utils.py # File utility functions | |
| │ └── words/ # Word list files | |
| │ ├── classic.txt # Default word list | |
| │ ├── fourth_grade.txt # Elementary word list | |
| │ └── wordlist.txt # Full word list | |
| ├── tests/ # Unit tests | |
| │ └── test_sprint6_integration.py # Comprehensive integration tests | |
| ├── specs/ # Documentation | |
| │ ├── specs.md # Game specifications | |
| │ ├── requirements.md # Implementation requirements | |
| │ └── wrdler_implementation_plan.md # Sprint planning summary | |
| ├── static/ # PWA assets | |
| │ ├── manifest.json # PWA manifest | |
| │ ├── service-worker.js # Service worker for offline caching | |
| │ └── icons/ # App icons | |
| ├── .env # Environment variables (HF credentials) | |
| ├── pyproject.toml # Project metadata | |
| ├── requirements.txt # Dependencies | |
| ├── uv.lock # UV lock file | |
| ├── Dockerfile # Container deployment | |
| ├── README.md # User-facing documentation | |
| ├── CLAUDE.md # This file - project context for Claude | |
| ├── GAMEPLAY_GUIDE.md # User guide with tips and strategies | |
| └── RELEASE_NOTES_v0.0.4.md # Complete release documentation | |
| ``` | |
| ## Key Features | |
| ### Game Modes | |
| 1. **Classic Mode:** Allows consecutive guessing after correct answers | |
| 2. **Too Easy Mode:** Single guess per reveal | |
| ### Audio & Visual Effects | |
| - **Background Music:** Toggleable ocean-themed background music with volume control | |
| - **Sound Effects:** Hit/miss/correct/incorrect guess sounds with volume control | |
| - **Ocean Theme:** Gradient animated background with wave effects | |
| - **Incorrect Guess History:** Visual display of wrong guesses (toggleable in settings) | |
| ### ✅ Challenge Mode & Remote Storage (v0.2.20+) | |
| - **Game ID System:** Short URL-based challenge sharing | |
| - Format: `?game_id=<sid>` in URL (shortened URL reference) | |
| - Each player gets different random words from the same wordlist | |
| - Enables fair challenges between players | |
| - Stored in Hugging Face dataset repository | |
| - **Remote Storage via HuggingFace Hub:** | |
| - Per-game settings JSON in `games/{uid}/settings.json` | |
| - Shortened URL mapping in `shortener.json` | |
| - Multi-user leaderboards with score, time, and difficulty tracking | |
| - Results sorted by: highest score → fastest time → highest difficulty | |
| - **Challenge Features:** | |
| - Submit results to existing challenges | |
| - Create new challenges from any completed game | |
| - Top 5 leaderboard display in Challenge Mode banner | |
| - Optional player names (defaults to "Anonymous") | |
| - Word list difficulty calculation and display (v0.2.29) | |
| - "Show Challenge Share Links" toggle (default OFF) to control URL visibility (v0.2.27) | |
| ### ✅ Progressive Web App (PWA) Support (v0.2.28+) | |
| - **PWA Installation:** App is installable as a Progressive Web App on desktop and mobile | |
| - Service worker for basic offline caching of static assets | |
| - Manifest.json with app metadata and icons | |
| - Platform-specific installation instructions in INSTALL_GUIDE.md | |
| - No gameplay logic changes required | |
| - Works offline for basic functionality | |
| ### PLANNED: Local Player Storage (v0.3.0) | |
| - **Local Storage:** | |
| - Location: `~/.wrdler/data/` | |
| - Files: `game_results.json`, `highscores.json` | |
| - Privacy-first: no cloud dependency, offline-capable | |
| - **Personal High Scores:** | |
| - Top 100 scores tracked automatically on local machine | |
| - Filterable by wordlist and game mode | |
| - High score sidebar expander display | |
| - **Player Statistics:** | |
| - Games played, average score, best score | |
| - Fastest completion time | |
| - Per-player history on local device | |
| ### Puzzle Generation | |
| - Horizontal-only word placement (one per row in 8×6 grid) | |
| - **Word length distribution:** Each puzzle contains exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words | |
| - Deterministic seeding support for reproducible puzzles | |
| - No word spacing configuration (fixed one word per row) | |
| - Validation ensures no overlaps, proper bounds, correct word distribution | |
| ### UI Components (v0.0.2 - Implemented) | |
| - **Game Grid:** Interactive 8×6 button grid (48 cells) with responsive layout | |
| - **Free Letter Selection:** Circular green gradient buttons (2 at game start) | |
| - **Score Panel:** Real-time scoring with client-side JavaScript timer | |
| - **Settings Sidebar:** | |
| - Word list picker (classic, fourth_grade, wordlist) | |
| - Game mode selector (Classic, Too Easy) | |
| - Audio volume controls (music and effects separate) | |
| - Toggle for incorrect guess history display | |
| - Player name input | |
| - "Show Challenge Share Links" toggle (default OFF) | |
| - Enable/disable sound effects checkbox | |
| - Enable/disable background music checkbox | |
| - **Theme System:** Ocean gradient background with CSS animations | |
| - **Game Over Dialog:** Final score display with tier ranking | |
| - **Incorrect Guess Display:** Shows history of wrong guesses with count | |
| - **Challenge Mode UI:** | |
| - Challenge Mode banner with leaderboard (top 5 players) | |
| - Share challenge button in game over dialog | |
| - Submit result or create new challenge options | |
| - Word list difficulty display | |
| - **PLANNED (v0.3.0):** Local high scores expander and personal statistics display | |
| ### Development Status | |
| **Current Version:** v0.0.4 (Complete) | |
| - ✅ All 7 sprints complete | |
| - ✅ 100% test coverage (25/25 tests) | |
| - ✅ Ready for production deployment | |
| - ✅ PWA support implemented | |
| - ✅ Challenge Mode fully functional | |
| - 📊 Development time: ~12.75 hours (sprints 1-7) | |
| - 📚 Complete documentation | |
| **Next Version:** v0.3.0 (Planned) | |
| - 📋 Local storage module (`wrdler/local_storage.py`) | |
| - 📋 Personal high score tracking (local JSON files) | |
| - 📋 High score sidebar UI display | |
| - 📋 Player statistics tracking and display | |
| ## Data Models | |
| ### Core Classes | |
| ```python | |
| @dataclass | |
| class Coord: | |
| x: int # row, 0-based | |
| y: int # col, 0-based | |
| @dataclass | |
| class Word: | |
| text: str | |
| start: Coord | |
| direction: Direction # "H" or "V" | |
| cells: List[Coord] | |
| @dataclass | |
| class Puzzle: | |
| words: List[Word] | |
| radar: List[Coord] | |
| may_overlap: bool | |
| spacer: int | |
| uid: str # Unique identifier for caching | |
| @dataclass | |
| class GameState: | |
| grid_size: int | |
| puzzle: Puzzle | |
| revealed: Set[Coord] | |
| guessed: Set[str] | |
| score: int | |
| last_action: str | |
| can_guess: bool | |
| game_mode: str | |
| points_by_word: Dict[str, int] | |
| start_time: Optional[datetime] | |
| end_time: Optional[datetime] | |
| ``` | |
| ## Development Workflow | |
| ### Running Locally | |
| ```bash | |
| # Install dependencies | |
| uv pip install -r requirements.txt --link-mode=copy | |
| # Run app | |
| uv run streamlit run app.py | |
| # or | |
| streamlit run app.py | |
| ``` | |
| ### Docker Deployment | |
| ```bash | |
| docker build -t wrdler . | |
| docker run -p 8501:8501 wrdler | |
| ``` | |
| ### Testing | |
| ```bash | |
| pytest tests/ | |
| ``` | |
| ### Environment Variables (for Challenge Mode) | |
| Challenge Mode requires HuggingFace Hub access for remote storage. Create a `.env` file in the project root: | |
| ```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_...` | |
| **HF_REPO_ID Structure:** | |
| The dataset repository will contain: | |
| - `shortener.json` - Short URL mappings | |
| - `games/{uid}/settings.json` - Per-game challenge data | |
| - `games/{uid}/result.json` - Optional detailed results | |
| **Note:** The app will work without these variables but Challenge Mode features (sharing, leaderboards) will be disabled. | |
| ## Git Configuration & Deployment | |
| **Current Branch:** main | |
| **Purpose:** Wrdler - vocabulary puzzle game with simplified 8x6 grid | |
| **Main Branch:** main | |
| ### Remotes | |
| - **ONCORP (origin):** https://github.com/Oncorporation/Wrdler.git (main repository) | |
| - **Hugging Face Spaces:** https://huggingface.co/spaces/[USERNAME]/Wrdler (live deployment) | |
| ### Deployment Platforms | |
| 1. **Hugging Face Spaces** (Primary) - Dockerfile deployment | |
| 2. **Local Development** - Streamlit run | |
| 3. **Docker** - Containerized deployment | |
| 4. **PWA** - Installable web app on any platform | |
| ## Sprint Summary (v0.0.2 - Complete) | |
| | Sprint | Description | Time | Tests | Status | | |
| |--------|-------------|------|-------|--------| | |
| | Sprint 1 | Core Data Models | 3h | 13/13 ✅ | Complete | | |
| | Sprint 2 | Puzzle Generator | 3h | 5/5 ✅ | Complete | | |
| | Sprint 3 | Remove Radar | 0.5h | N/A | Complete | | |
| | Sprint 4 | Free Letters UI | 2h | Manual ✅ | Complete | | |
| | Sprint 5 | Grid UI Updates | 1.25h | Syntax ✅ | Complete | | |
| | Sprint 6 | Integration Testing | 2h | 7/7 ✅ | Complete | | |
| | Sprint 7 | Documentation | 1h | N/A | Complete | | |
| | **Total** | **All Features** | **12.75h** | **25/25** | **Complete ✅** | | |
| **Status:** Ready for deployment! 🚀 | |
| ## Post-v0.0.2 Enhancements | |
| ### v0.2.20-0.2.29 (Challenge Mode & PWA) | |
| - Remote storage and game sharing via HF datasets | |
| - Multi-user leaderboards | |
| - PWA support with offline caching | |
| - Word list difficulty calculation | |
| - Privacy controls for challenge sharing | |
| - Sound effect and music system improvements | |
| ## Future Roadmap | |
| ### v0.3.0 (Next Phase) | |
| - Local persistent storage module (`~/.wrdler/data/`) | |
| - High score tracking and display | |
| - Player statistics tracking | |
| - Enhanced UI animations | |
| ### v1.0.0 (Long Term) | |
| - Multiple difficulty levels | |
| - Daily puzzle mode | |
| - Internationalization (i18n) | |
| - Performance optimizations | |
| - Advanced word list management | |
| ## Deployment Targets | |
| - **Hugging Face Spaces:** Primary deployment platform (Dockerfile-based) | |
| - **Docker:** Containerized deployment for any platform | |
| - **Local:** Development and testing | |
| - **PWA:** Installable on desktop and mobile devices | |
| ### Privacy & Data (v0.0.4) | |
| - **Challenge Mode:** Optional remote storage via Hugging Face datasets | |
| - Player names optional (defaults to "Anonymous") | |
| - Only stores: word lists, scores, times, game modes | |
| - No PII beyond optional player name | |
| - User controls URL visibility via "Show Challenge Share Links" toggle | |
| - **Local Storage (v0.3.0 - Planned):** | |
| - Location: `~/.wrdler/data/` | |
| - Privacy-first, offline-capable | |
| - Easy to delete | |
| - No cloud dependency | |
| ## Notes for Claude | |
| ### Technical Implementation | |
| - ✅ 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 | |
| - ✅ 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 | |
| - ✅ Game IDs are deterministic for consistent sharing | |
| - ✅ 8×6 rectangular grid (grid_rows=6, grid_cols=8) | |
| - ✅ Horizontal-only word placement (one per row) | |
| - ✅ Radar/scope visualization removed entirely | |
| - ✅ Free letter selection UI implemented with circular buttons | |
| - ✅ PWA injection via Docker build script (`inject-pwa-head.sh`) | |
| ### Key Implementation Details | |
| - **No radar field in Puzzle dataclass** - removed in Sprint 3 | |
| - **No vertical word placement** - horizontal only ("H" direction) | |
| - **Fixed grid dimensions** - always 8x6 (grid_cols=8, grid_rows=6) | |
| - **One word per row** - exactly 6 words total | |
| - **Word length requirement** - exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words per puzzle | |
| - **Free letters tracked** - `free_letters` set and `free_letters_used` counter | |
| - **Auto-completion** - words auto-marked when all letters revealed | |
| - **Incorrect guess limit** - maximum 10 per game | |
| ### WSL Environment Python Versions | |
| The development environment is WSL (Windows Subsystem for Linux) with access to both native Linux and Windows Python installations: | |
| **Native WSL (Linux):** | |
| - `python3` → Python 3.10.12 (`/usr/bin/python3`) | |
| - `python3.10` → Python 3.10.12 | |
| **Windows Python (accessible via WSL):** | |
| - `python311.exe` → Python 3.11.9 (`/mnt/c/Users/cfettinger/AppData/Local/Programs/Python/Python311/`) | |
| - `python3.13.exe` → Python 3.13.1 (`/mnt/c/ProgramData/chocolatey/bin/`) | |
| **Note:** Windows Python executables (`.exe`) can be invoked directly from WSL and are useful for testing compatibility across Python versions. The project targets Python 3.12.8 specifically but requires >=3.12, <3.13 per pyproject.toml. | |
| ## Documentation Structure | |
| This file (CLAUDE.md) serves as a **living context document** for AI-assisted development: | |
| - **[specs/specs.md](specs/specs.md)** - Game rules, requirements, and feature specifications | |
| - **[specs/requirements.md](specs/requirements.md)** - Implementation requirements and acceptance criteria | |
| - **[GAMEPLAY_GUIDE.md](GAMEPLAY_GUIDE.md)** - User guide with tips and strategies | |
| - **[INSTALL_GUIDE.md](INSTALL_GUIDE.md)** - PWA installation instructions | |
| - **[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 | |
| **When to use each:** | |
| - **specs.md** - Understanding game rules and scoring system | |
| - **requirements.md** - Implementation status and acceptance criteria | |
| - **CLAUDE.md** - Quick reference for codebase and development context | |
| - **GAMEPLAY_GUIDE.md** - How to play the game | |
| - **README.md** - Public-facing info, setup instructions, and complete changelog | |
| - **INSTALL_GUIDE.md** - Installing Wrdler as a PWA | |
| - **Dockerfile** - Deployment configuration and container setup | |
| ## Challenge Mode & Remote Storage | |
| - ✅ Challenge Mode allows sharing games via short links (`?game_id=<sid>`) | |
| - ✅ Results stored in Hugging Face dataset repos via `game_storage.py` | |
| - ✅ Leaderboard sorted by: highest score → fastest time → highest difficulty | |
| - ✅ Multi-user challenges with top 5 display | |
| - ✅ Optional sharing (controlled by "Show Challenge Share Links" toggle, default OFF) | |
| - ✅ Word list difficulty calculation (v0.2.29) | |
| - ✅ iframe embedding support with `&iframe_host=` parameter (v0.2.23) | |
| ## Known Issues | |
| ### Active | |
| - ❓ 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. | |
| ### Resolved | |
| - ✅ Duplicate rendering call bug (fixed in v0.0.2) | |
| - ✅ Music looping on congratulations screen (fixed in v0.2.12) | |
| - ✅ Sound effect and music volume wiring (fixed in v0.2.18, v0.2.19) | |
| - ✅ Sonar grid alignment (removed in Sprint 3) | |
| - ✅ Challenge mode link issues (fixed in v0.2.22) | |
| ## Dependencies | |
| From `requirements.txt`: | |
| - streamlit>=1.51.0 (primary framework) | |
| - matplotlib>=3.8 (visualization) | |
| - requests>=2.31.0 (HTTP requests) | |
| - huggingface_hub>=0.20.0 (remote storage) | |
| - python-dotenv>=1.0.0 (environment variables) | |
| From `pyproject.toml`: | |
| - Python >=3.12, <3.13 (strict version requirement) | |
| ## Version History Summary | |
| - **v0.0.4** (Current) - Documentation sync, version update | |
| - **v0.0.2-0.0.3** - All 7 sprints complete, core Wrdler features | |
| - **v0.2.20-0.2.29** - Challenge Mode, PWA, remote storage (inherited from BattleWords) | |
| - **v0.1.x** - Initial BattleWords releases before Wrdler fork | |
| See README.md for complete changelog. | |
| --- | |
| **Last Updated:** 2025-01-31 | |
| **Current Version:** 0.0.4 | |
| **Status:** Production Ready - All Features Complete ✅ | |
| ## 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. | |