CLAUDE.md

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.1.2 Repository: https://github.com/Oncorporation/Wrdler.git Live Demo: [DEPLOYMENT_URL_HERE]

Recent Changes

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
• ✅ 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
• ✅ AI word generation functionality added
• ✅ Word list management enhanced with AI support
• ✅ Utility modules integrated
• ✅ 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 (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)
• Remote Storage: huggingface_hub (>=0.20.0)
• Environment: python-dotenv (>=1.0.0)
• AI Generation: transformers, gradio_client
• Testing: Pytest
• Package Manager: UV or pip

Project Structure

wrdler/
├── app.py                    # Streamlit entry point
├── wrdler/                   # Main package
│   ├── __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
│   ├── 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
├── style_wrdler.css         # Custom CSS styling for Gradio interface
├── 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.1.0.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

✅ AI Word Generation (v0.1.0+)

• AI-Powered Word Lists: Generate custom word lists using Hugging Face Spaces or local transformers
• Topic-Based Generation: Create words related to specific themes (e.g., "Ocean Life", "Space")
• Automatic Word Expansion: New AI-generated words are saved to local files for future use
  • Intelligent word detection: separates existing dictionary words from new AI-generated words
  • Only new words are saved to prevent duplicates
  • Automatic retry mechanism (up to 3 attempts) if insufficient words generated
  • 1000-word file size limit prevents dictionary bloat
  • Files auto-sorted by length then alphabetically
• Fallback Support: Gracefully falls back to dictionary words if AI is unavailable
• Word Distribution: Ensures exactly 25 words each of lengths 4, 5, and 6 per topic
• Dual Generation Modes:
  • HF Space API (primary): Uses Hugging Face Space for word generation when USE_HF_WORDS=true
  • Local Models (fallback): Falls back to local transformers models if HF Space unavailable
• Enhanced Logging: Detailed pipeline visibility for debugging and monitoring

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, AI Generated)
  • 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: 0.1.2 (Complete)

• ✅ All 7 sprints complete
• ✅ 100% test coverage (25/25 tests)
• ✅ AI word generation implemented
• ✅ 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

@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

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

# 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

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

Testing

pytest tests/

Environment Variables (for Challenge Mode)

Challenge Mode requires HuggingFace Hub access for remote storage. Create a .env file in the project root:

# 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.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)
• 1000-word file size limit to prevent dictionary bloat
• Improved new word detection (separates existing vs. new words)
• 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
• Topic-based word creation with automatic saving
• Enhanced word list management with AI fallback
• Utility modules integration for storage and file handling

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.1.0)

• 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
• ✅ 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
• ✅ 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)
• ✅ 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
  • 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
• 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
• 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

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 - Game rules, requirements, and feature specifications
• specs/requirements.md - Implementation requirements and acceptance criteria
• GAMEPLAY_GUIDE.md - User guide with tips and strategies
• INSTALL_GUIDE.md - PWA installation instructions
• README.md - User-facing documentation, installation guide, and complete changelog
• Dockerfile - Container deployment configuration with PWA injection
• pyproject.toml - Python project metadata and dependencies
• Gradio 6 Migration Guide - Official Gradio migration reference (external)

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
• Gradio Migration Guide - Gradio 5.x/6.x compatibility and best practices

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)
• gradio>=5.50 (alternative UI 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)
• transformers (AI word generation)
• gradio_client (HF Space API)

From pyproject.toml:

• Python >=3.12, <3.13 (strict version requirement)

Version History Summary

• 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
• v0.2.20-0.2.29 - Challenge Mode, PWA, remote storage (inherited from BattleWords)
• v0.1.x - Initial BattleWords releases before Wrdler fork

---

Last Updated: 2025-11-29 Current Version: 0.1.2 Status: Production Ready - Gradio UI Enhanced ✅