| # Wrdler - Project Context | |
| ## Project Overview | |
| Wrdler is a simplified vocabulary puzzle game based on BattleWords: | |
| - **Python project** (Streamlit, Python 3.12.8) | |
| - **8x6 grid** (8 columns × 6 rows, one word per row, horizontal only) | |
| - **No scope/radar visualization** | |
| - **2 free letter guesses at game start** (all instances revealed) | |
| - **Word composition:** 2 four-letter, 2 five-letter, 2 six-letter words per puzzle | |
| **Current Version:** 0.2.4 | |
| **Repository:** https://github.com/Oncorporation/Wrdler.git | |
| **Branch:** AI (working branch) | |
| ## Current Features (v0.2.4) | |
| ### Core Gameplay | |
| - 8x6 grid with 6 hidden words (one per row, horizontal only) | |
| - Players choose 2 free letters at start; all instances are revealed | |
| - Click cells to reveal letters or empty spaces | |
| - Guess words for points (word length + bonus for unrevealed letters) | |
| - Game ends when all words guessed or all word letters are revealed | |
| - Incorrect guess history display (toggleable, default enabled) | |
| - 10 incorrect guess limit per game | |
| ### Game Modes | |
| 1. **Classic Mode:** Allows consecutive guessing after correct answers | |
| 2. **Too Easy Mode:** Single guess per reveal | |
| ### Scoring Tiers | |
| - **Legendary:** 45+ points | |
| - **Fantastic:** 42-44 points | |
| - **Great:** 39-41 points | |
| - **Good:** 35-38 points | |
| - **Keep practicing:** < 35 points | |
| ### Word List Management | |
| - Sidebar controls for sorting and filtering word lists | |
| - Filter capability using `assets/filter.txt` blocklist to remove unwanted words | |
| - Dialog display of removed words after filtering | |
| ### Challenge Mode & Remote Storage | |
| - Short URL-based challenge sharing via `?game_id=<sid>` | |
| - Each player gets different random words from same wordlist | |
| - Multi-user challenge leaderboards (top 5 display) | |
| - Remote storage via HuggingFace datasets | |
| - Word list difficulty calculation | |
| - "Show Challenge Share Links" toggle (default OFF) | |
| - **Integration:** | |
| - Automatic submission after game completion (opt-in via game over popup) | |
| - 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) | |
| **Access:** 'Leaderboard' link in the footer navigation at the bottom of the page | |
| ### Daily & Weekly Leaderboards | |
| - **Settings-Based Separation:** Each unique settings combo creates separate leaderboard | |
| - Settings: `game_mode`, `wordlist_source`, `show_incorrect_guesses`, `enable_free_letters`, `puzzle_options` (spacer, may_overlap) | |
| - **Auto Score Submission:** Checks qualification for top 25 after game completion | |
| - **Storage:** Folder-based discovery at `games/leaderboards/{daily|weekly}/{period}/{file_id}/settings.json` | |
| - **File ID Format:** `{wordlist_source}-{game_mode}-{sequence}` (e.g., `classic-classic-0`) | |
| - **Leaderboard Page:** Four tabs (Today, Daily, Weekly, History) accessible via `?page=today|daily|weekly|history` | |
| - Leaderboard files use UTC for all 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]` | |
| ### AI Word Generation | |
| - Topic-based word list generation via HuggingFace Spaces or local transformers | |
| - Automatic word saving (max 1000 words per file) | |
| - Retry mechanism (up to 3 attempts) for insufficient word counts | |
| - Fallback to dictionary words if AI unavailable | |
| ### Audio & Visuals | |
| - Ocean-themed gradient background with wave animations | |
| - Toggleable background music with volume control | |
| - Sound effects (hit/miss/correct/incorrect) with volume control | |
| ### PWA Support | |
| - Installable as Progressive Web App on desktop and mobile | |
| - Service worker for offline caching of static assets | |
| - Works offline for basic functionality | |
| ## Technical Architecture | |
| ### Technology Stack | |
| - **Framework:** Streamlit 1.51.0 | |
| - **Language:** Python 3.12.8 (requires >=3.12, <3.13) | |
| - **Remote Storage:** huggingface_hub (>=0.20.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.2.0 | |
| │ ├── 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 with query param routing | |
| │ ├── oauth.py # HuggingFace OAuth utilities (NEW) | |
| │ ├── settings_page.py # Settings page UI (IN PROGRESS) | |
| │ ├── leaderboard.py # Leaderboard system (daily/weekly) | |
| │ ├── leaderboard_page.py # Leaderboard UI page | |
| │ ├── word_loader.py # Word list management | |
| │ ├── word_loader_ai.py # AI word generation | |
| │ ├── 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 (with folder listing) | |
| │ │ ├── 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 | |
| ├── tests/ # Unit tests | |
| ├── specs/ # Documentation | |
| ├── static/ # PWA assets (manifest.json, service-worker.js) | |
| ├── .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 | |
| ├── 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 | |
| ``` | |
| ### Page Navigation System | |
| Uses **query parameter-based routing** (NOT Streamlit multi-page): | |
| - `?page=today|daily|weekly|history` → Leaderboard pages | |
| - `?page=settings` → Settings page (IN PROGRESS - OAuth protected) | |
| - `?game_id=<sid>` → Challenge mode | |
| - No query params → Main game page | |
| ## 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] | |
| may_overlap: bool | |
| spacer: int | |
| uid: str # Unique identifier | |
| @dataclass | |
| class GameState: | |
| grid_rows: int # 6 for Wrdler | |
| grid_cols: int # 8 for Wrdler | |
| 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] | |
| ``` | |
| ## Environment Variables | |
| Create a `.env` file in the project root: | |
| ```bash | |
| # Challenge Mode & Leaderboards (Remote Storage) | |
| HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx # HuggingFace API token with write access | |
| HF_REPO_ID=YourUsername/YourRepo # Dataset repo for challenge storage | |
| # AI Word Generation | |
| USE_HF_WORDS=false # Enable HF Space API for word generation | |
| HF_WORD_LIST_REPO_ID=YourUsername/WordRepo # Dataset repo for AI word lists | |
| # OAuth Admin Access (NEW) | |
| ADMIN_USERS=username1,username2 # Comma-separated list of admin usernames | |
| MAX_DISPLAY_ENTRIES=25 # Max leaderboard entries to display (default: 25) | |
| ``` | |
| ### HF_REPO_ID Structure | |
| ``` | |
| HF_REPO_ID/ | |
| ├── shortener.json # URL shortener mappings | |
| ├── games/{uid}/settings.json # Challenge data (entry_type: "challenge") | |
| └── games/leaderboards/ | |
| ├── daily/{YYYY-MM-DD}/{file_id}/settings.json # Daily leaderboards | |
| └── weekly/{YYYY-Www}/{file_id}/settings.json # Weekly leaderboards | |
| ``` | |
| ## Development Workflow | |
| ### Running Locally | |
| ```bash | |
| # Install dependencies | |
| uv pip install -r requirements.txt --link-mode=copy | |
| # Run app | |
| streamlit run app.py | |
| ``` | |
| ### Testing | |
| ```bash | |
| pytest tests/ | |
| ``` | |
| ## Next Step: OAuth-Protected Settings Page | |
| ### Goal | |
| Move all game settings from sidebar to a dedicated settings page at `?page=settings`, protected by HuggingFace OAuth (admin-only access). | |
| ### Implementation Approach | |
| 1. **Use existing query parameter routing** (like leaderboard pages) | |
| 2. **HuggingFace OAuth integration:** | |
| - Add `hf_oauth: true` to README.md YAML header ✅ DONE | |
| - Create `wrdler/oauth.py` with utility functions ✅ DONE | |
| - OAuth user info available at `st.session_state["oauth_user"]` | |
| - Check admin access via `ADMIN_USERS` environment variable | |
| 3. **Create `wrdler/settings_page.py`:** | |
| - Check authentication with `require_admin()` from oauth.py | |
| - Move settings UI from sidebar (word list, game mode, audio, etc.) | |
| - Persist settings to session state | |
| - Accessible via `?page=settings` | |
| 4. **Modify `wrdler/ui.py`:** | |
| - Add settings page route handler (similar to leaderboard routing) | |
| - Remove settings from sidebar (keep minimal controls only) | |
| - Add "⚙️ Settings" link in footer navigation | |
| 5. **Keep sidebar minimal:** | |
| - Version info | |
| - User info (if logged in) | |
| - Link to settings page | |
| ### HuggingFace OAuth Flow | |
| 1. User clicks login button (HF Spaces provides this automatically) | |
| 2. User authorizes with HF account | |
| 3. HF redirects back with OAuth token | |
| 4. User info stored in `st.session_state["oauth_user"]` | |
| 5. Check `username` against `ADMIN_USERS` env var | |
| 6. Grant/deny access to settings page | |
| ### Files to Modify | |
| - `wrdler/ui.py` - Add settings page routing, remove sidebar settings | |
| - `wrdler/settings_page.py` - NEW FILE - Settings UI with OAuth protection | |
| - `wrdler/oauth.py` - Already created ✅ | |
| ### Key OAuth Functions (wrdler/oauth.py) | |
| ```python | |
| get_user_info() → Dict | None # Get authenticated user info | |
| get_username() → str | None # Get username (preferred_username) | |
| is_authenticated() → bool # Check if user is logged in | |
| is_admin(allowed_users) → bool # Check if user is admin | |
| require_admin(page_name) → bool # Validate admin access or show error | |
| ``` | |
| ## Technical Notes | |
| ### Important Implementation Details | |
| - **Python syntax only** - Use colons `:` not braces `{}` | |
| - **8×6 grid:** `grid_rows=6`, `grid_cols=8` | |
| - **Horizontal-only placement:** One word per row | |
| - **Query param routing:** All pages use `?page=<name>` system | |
| - **Session state management:** Heavy use of `st.session_state` | |
| - **OAuth detection:** Check `st.session_state.get("oauth_user")` | |
| ### Current Routing Pattern (ui.py) | |
| ```python | |
| params = st.query_params | |
| page = params.get("page", "") | |
| if page in {"today", "daily", "weekly", "history"}: | |
| render_leaderboard_page(default_tab=page) | |
| return | |
| if page == "settings": # TO BE IMPLEMENTED | |
| render_settings_page() | |
| return | |
| # Default: main game page | |
| run_app() | |
| ``` | |
| ## Deployment Platforms | |
| 1. **HuggingFace Spaces** (Primary) - Dockerfile deployment with OAuth support | |
| 2. **Local Development** - Streamlit run | |
| 3. **Docker** - Containerized deployment | |
| ## Git Configuration | |
| - **Current Branch:** AI (working branch) | |
| - **Main Branch:** main | |
| - **Remotes:** | |
| - origin: https://github.com/Oncorporation/Wrdler.git | |
| - Hugging: https://huggingface.co/spaces/Surn/Wrdler | |