Hugging Face's logo

Spaces:
Surn
/
wrdler
Running

App Files Community
wrdler / CLAUDE.md
Surn's picture
Surn
fix word distribution
5f8a848
preview code
|
raw
history blame contribute delete
19.9 kB

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 

@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 app
uv run streamlit run app.py
# or
streamlit run app.py

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

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:

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.