specs/specs.md

Wrdler Game Specifications (specs.md)

Version: 0.2.4 Status: Production Ready - Leaderboards Implemented Last Updated: 2025-12-08

Overview

Wrdler is a Python/Streamlit 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

• Python project (Streamlit, Python 3.12.8)
• 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:
  • Legendary: 45+ points
  • Fantastic: 42-44 points
  • Great: 39-41 points
  • Good: 35-38 points
  • Keep practicing: <35 points
• 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.2.4)

Word List Management (v0.2.4)

• ✅ Filter Wordlist: Remove words found in assets/filter.txt from the selected word list
• ✅ Sort Wordlist: Sort words by length and alphabetically
• ✅ Feedback: Dialog showing count and list of removed words

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

Leaderboard System (v0.2.1) ✅ IMPLEMENTED

Wrdler features a comprehensive daily and weekly leaderboard system:

Core Features:

• Daily Leaderboards: Top 20 scores for each day (resets UTC midnight)
• Weekly Leaderboards: Top 20 scores for each ISO week (resets Monday UTC 00:00)
• Settings-Based Separation: Each unique combination of game-affecting settings creates a separate leaderboard:
  • game_mode (classic, easy, too easy)
  • wordlist_source (classic.txt, fourth_grade.txt, etc.)
  • show_incorrect_guesses (boolean)
  • enable_free_letters (boolean)
  • puzzle_options (spacer, may_overlap)
• Sorting: Scores sorted by: score (desc) → time (asc) → difficulty (desc)
• Qualification: Only top 25 (configurable) scores displayed per leaderboard (more can be stored)

Storage Structure:

HF_REPO_ID/games/
├── leaderboards/
│   ├── daily/{YYYY-MM-DD}/{file_id}/settings.json
│   └── weekly/{YYYY-Www}/{file_id}/settings.json
└── {challenge_id}/settings.json

File ID Format: {wordlist_source}-{game_mode}-{sequence}

• Example: classic-classic-0, easy-too_easy-1
• Sanitized (no .txt, lowercase, underscores for spaces)

Leaderboard Page UI:

• Today Tab: Current daily and weekly leaderboards
  • Query params: ?gidd={file_id} and ?gidw={file_id} for filtering
  • Side-by-side display in two columns
• Daily Tab: Last 7 days of daily leaderboards
  • Expandable groups per date
  • All settings combinations shown
• Weekly Tab: Current ISO week leaderboard
  • All settings combinations displayed
• History Tab: Historical leaderboard browser
  • Dropdown selectors for period and settings
  • Separate daily and weekly columns

Integration:

• Automatic submission after game completion (opt-in)
• Challenge scores also contribute to daily/weekly leaderboards
• Source tracking via source_challenge_id field
• Unified JSON format with entry_type field (daily/weekly/challenge)

Discovery: Folder-based (no index.json)

• Scans period folders for date/week IDs
• Filters by file_id prefix for matching settings
• Loads and verifies full settings match

Date Display Updates:

• All leaderboard files use UTC for period boundaries.
• When displaying daily leaderboards, show the UTC period as a PST date range.
• Example: For UTC file date 2025-12-08, display: 2025-12-08 00:00:00 UTC to 2025-12-08 23:59:59 UTC and 2025-12-07 16:00:00 PST to 2025-12-08 15:59:59 PST The leaderboard expander label should show: Mon, Dec 08, 2025 4:00 PM PST – Tue, Dec 09, 2025 3:59:59 PM PST [settings badge]

Access: 'Leaderboard' link in the footer navigation at the bottom of the page

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

Settings Page (Planned/Upcoming)

• Move all game settings from sidebar to a dedicated settings page (?page=settings) requiring a logged in user (OAuth)

Storage

Current (v0.2.1)

• ✅ Challenge Mode uses remote storage via Hugging Face datasets
• ✅ Game ID is generated from the word list for replay/sharing

Planned (Future)

• Local persistent storage for game results and high scores (JSON files)
• Local storage location: ~/.wrdler/data/
• Privacy-first offline access

UI Elements (v0.2.1 - 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:

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:

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/
    ├── leaderboards/
    │   ├── daily/
    │   │   └── {YYYY-MM-DD}/          # Daily period folders
    │   │       └── {file_id}/         # Settings-specific leaderboard
    │   │           └── settings.json  # entry_type: "daily"
    │   └── weekly/
    │       └── {YYYY-Www}/            # Weekly period folders (ISO week)
    │           └── {file_id}/         # Settings-specific leaderboard
    │               └── settings.json  # entry_type: "weekly"
    └── {challenge_id}/
        └── settings.json              # Challenge data (entry_type: "challenge")

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.2.4 (Production Ready - Leaderboards Implemented)

Completed ✅

• v0.2.4: Word List Filtering

  • Added "Filter Wordlist" button to sidebar
  • Implemented blocklist filtering via assets/filter.txt
  • Added results dialog showing removed words

• v0.2.1: Daily and Weekly Leaderboards

  • Settings-based leaderboard separation
  • Folder-based discovery (no index.json)
  • Top 20 displayed entries per leaderboard
  • Four-tab leaderboard page (Today, Daily, Weekly, History)
  • Automatic score qualification and submission
  • Integration with challenge mode
  • Query parameter filtering for direct links
  • Settings page planned (move from sidebar, OAuth login required)

• 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

• Local persistent storage, high score tracking, player statistics, leaderboard caching (future)
• Enhanced UI animations, retry logic, rate limiting, archival script (future)
• AI difficulty tuning, multi-language word generation, i18n (future)

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.