# Wrdler Game Specifications (specs.md)
**Version:** 0.1.1
**Status:** Production Ready - AI Enhanced
**Last Updated:** 2025-01-31

## Overview
Wrdler is a simplified vocabulary puzzle game based on BattleWords, but with key differences. The objective is to discover hidden words on a grid by making strategic guesses and using free letter reveals at the game start.

**Current Status:** All 7 sprints complete, 100% tested, fully documented

## Key Differences from BattleWords
- **8x6 grid** (instead of 12x12)
- **One word per row** (instead of 6 words placed anywhere)
- **Horizontal words only** (no vertical placement)
- **No scope/radar visualization**
- **2 free letter guesses at game start** (all instances of chosen letters are revealed)

## Game Board
- 8 x 6 grid
- Six hidden words:
  - One word per row (row 0-5)
  - **Word composition:** Exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
  - All placed horizontally (left-right)
  - No vertical placement
  - No diagonal placement
  - Words do not overlap
- Entry point is `app.py`
- **Supports Dockerfile-based deployment for Hugging Face Spaces and other container platforms**

## Gameplay (Core)
- Players start by choosing 2 letters; all instances of those letters are revealed in the grid
- Players click grid squares to reveal letters or empty spaces
- Empty revealed squares are styled with CSS class `empty`
- After any reveal, the app immediately reruns (`st.rerun`) to show the change
- After revealing a letter, players may guess a word by entering it in a text box
- Guess submission triggers an immediate rerun to reflect results
- Only one guess per letter reveal; must uncover another letter before guessing again
- In the default mode, a correct guess allows chaining an additional guess without another reveal
- **The game ends when all six words are guessed or all word letters are revealed**

## Scoring
- Each correct word guess awards points:
  - 1 point per letter in the word
  - Bonus points for each hidden letter at the time of guessing
- Score tiers:
  - Good: 34-37
  - Great: 38-41
  - Fantastic: 42+
- **Game over is triggered by either all words being guessed or all word letters being revealed**

## Core Rules (v0.0.2 - Implemented)
- ✅ 8x6 grid with one word per row
- ✅ Horizontal words only; no vertical placement
- ✅ No overlaps: words do not overlap or share letters
- ✅ No radar/scope visualization (removed in Sprint 3)
- ✅ 2 free letter guesses at game start (implemented in Sprint 4)
- ✅ Incorrect guess history with optional display
- ✅ 10 incorrect guess limit per game
- ✅ Two game modes: Classic (chain guesses) and Too Easy (single guess per reveal)

## Implemented Features (v0.1.1)

### AI Word Generation (v0.1.0+)
- ✅ **Topic-Based Generation:** Create custom word lists for any theme using AI
- ✅ **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
- ✅ **Intelligent Word Management:**
  - Smart detection separates existing dictionary words from new AI-generated words
  - Only saves new words to prevent duplicates in word files
  - Automatic retry mechanism (up to 3 attempts) if insufficient words generated
  - 1000-word file size limit prevents dictionary bloat
  - Auto-sorted by length then alphabetically
- ✅ **Guaranteed Distribution:** Ensures exactly 25 words each of lengths 4, 5, and 6
- ✅ **Graceful Fallback:** Uses dictionary words if AI generation fails
- ✅ **Enhanced Logging:** Detailed pipeline visibility for debugging

### Challenge Mode
- ✅ **Game ID Sharing:** Each puzzle generates a shareable link with `?game_id=<sid>` to challenge others with the same word list
- ✅ **Remote Storage:** Game results and leaderboards stored in Hugging Face dataset repos
- ✅ **Leaderboards:** Multi-user leaderboards sorted by score (descending) then time (ascending)
- ✅ **Word List Difficulty:** Calculated and displayed for each challenge
- ✅ **Top 5 Display:** Leaderboard banner shows top 5 players
- ✅ **Optional Sharing:** "Show Challenge Share Links" toggle (default OFF) controls URL visibility

### PWA Support
- ✅ **PWA Installation:** App is installable as a Progressive Web App on desktop and mobile
  - Added `service worker` and `manifest.json`
  - Basic offline caching of static assets
  - INSTALL_GUIDE.md added with platform-specific install steps
  - No gameplay logic changes

## Storage

### Current (v0.0.2)
- ✅ Challenge Mode uses remote storage via Hugging Face datasets
- ✅ Game ID is generated from the word list for replay/sharing

### Planned (v0.3.0)
- 📋 Local persistent storage for game results and high scores (JSON files)
- 📋 Local storage location: `~/.wrdler/data/`
- 📋 Privacy-first offline access

## UI Elements (v0.0.2 - Implemented)
- ✅ 8x6 grid (48 cells total)
- ✅ Free letter guess buttons (2 at game start) - circular green gradient design
- ✅ Text box for word guesses
- ✅ Score display (shows word, base points, bonus points, total score)
- ✅ Guess status indicator (Correct/Try Again)
- ✅ Incorrect guess history display (toggleable)
- ✅ Game ID display and share button in game over dialog
- ✅ Challenge Mode banner with leaderboard (top 5)
- ✅ High score expander in sidebar
- ✅ Player name input in sidebar
- ✅ Checkbox: "Show Challenge Share Links" (default OFF)
  - When OFF:
    - Challenge Mode header hides the Share Challenge link
    - Game Over dialog still supports submitting/creating challenges, but does not display the generated share URL
  - Persisted in session state and preserved across "New Game"

## Word List
- External list at `wrdler/words/wordlist.txt`
- Loaded by `wrdler.word_loader.load_word_list()` with caching
- Filtered to uppercase A-Z, lengths in {4,5,6}; falls back if < 25 per length

## Generator
- Centralized word loader
- No duplicate word texts are selected
- Horizontal-only word placement
- One word per row in 8x6 grid
- **Word length distribution:** Each puzzle must contain exactly 2 four-letter words, 2 five-letter words, and 2 six-letter words
- No word spacing configuration (fixed one word per row)

## Entry Point
- The Streamlit entry point is `app.py`
- **A `Dockerfile` can be used for containerized deployment (recommended for Hugging Face Spaces)**

## Deployment Requirements

### Basic Deployment (Offline Mode)
No special configuration needed. The app will run with all core gameplay features.  
Optional: Install as PWA from the browser menu (Add to Home Screen/Install app).

### Challenge Mode Deployment (Remote Storage)
Requires HuggingFace Hub integration for challenge sharing and leaderboards.

**Required Environment Variables:**
```bash
HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx  # or HF_TOKEN (write access required)
HF_REPO_ID=YourUsername/YourRepo       # Target HF dataset repository
SPACE_NAME=YourUsername/Wrdler         # Your HF Space name for URL generation
```

**Optional Environment Variables:**
```bash
CRYPTO_PK=                             # Reserved for future challenge signing
```

**Setup Steps:**
1. Create a HuggingFace account at https://huggingface.co
2. Create a dataset repository (e.g., `YourUsername/WrdlerStorage`)
3. Generate an access token with `write` permissions:
   - Go to https://huggingface.co/settings/tokens
   - Click "New token"
   - Select "Write" access
   - Copy the token (starts with `hf_`)
4. Create a `.env` file in project root with the variables above
5. For Hugging Face Spaces deployment, add these as Space secrets

**Repository Structure (automatically created):**
```
HF_REPO_ID/
├── shortener.json                     # Short URL mappings (sid -> full URL)
└── games/
    └── {uid}/
        └── settings.json              # Challenge data with users array
```

**Data Privacy:**
- Challenge Mode stores: word lists, scores, times, game modes, player names
- No PII beyond optional player name (defaults to "Anonymous")
- Players control URL visibility via "Show Challenge Share Links" setting
- App functions fully offline when HF credentials not configured

**Deployment Platforms:**
- Local development: Run with `streamlit run app.py`
- Docker: Use provided `Dockerfile`
- Hugging Face Spaces: Dockerfile deployment (recommended)
- Any Python 3.10+ hosting with Streamlit support

## Development Status

**Current Version:** 0.1.1 (Production Ready - AI Enhanced)

### Completed ✅
- **v0.1.1:** Enhanced AI word generation
  - Intelligent word saving with duplicate prevention
  - Automatic retry mechanism (up to 3 attempts)
  - 1000-word file size limit
  - Improved HF Space API integration
  - Enhanced logging and error handling
  
- **v0.1.0:** AI word generation foundation
  - Topic-based word list creation
  - Dual generation modes (HF Space + local)
  - Utility modules integration
  
- **v0.0.2:** All 7 sprints complete
  - ✅ 100% test coverage (25/25 tests)
  - 📊 Development time: ~12.75 hours (sprints 1-7)
  - 📚 Complete documentation

### Future Roadmap
- **v0.3.0:** Local persistent storage, high score tracking, player statistics
- **v1.0.0:** Enhanced UX, multiple difficulty levels, daily puzzle mode

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

## 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.