Basic Only version step 2

LOCALHOST_PWA_README.md

@@ -1,267 +0,0 @@
-# PWA on Localhost - Important Information
-
-## Summary
-
-**The PWA files were created successfully**, but they **won't work fully on `localhost:8501`** due to Streamlit's static file serving limitations.
-
----
-
-## What You're Seeing (or Not Seeing)
-
-### ✅ What DOES Work on Localhost:
-
-1. **Game functionality**: Everything works normally
-2. **Challenge Mode**: Loading `?game_id=...` works (if HF credentials configured)
-3. **PWA meta tags**: Injected into HTML (check page source)
-4. **Service worker registration attempt**: Runs in browser console
-
-### ❌ What DOESN'T Work on Localhost:
-
-1. **`manifest.json` not accessible**:
-   ```
-   http://localhost:8501/app/static/manifest.json
-   → Returns HTML instead of JSON (Streamlit doesn't serve /app/static/)
-   ```
-
-2. **Icons not accessible**:
-   ```
-   http://localhost:8501/app/static/icon-192.png
-   → Returns 404 or HTML
-   ```
-
-3. **Service worker fails to register**:
-   ```javascript
-   // Browser console shows:
-   Failed to register service worker: 404 Not Found
-   ```
-
-4. **No PWA install prompt**:
-   - No banner at bottom of screen
-   - No install icon in address bar
-   - PWA features disabled
-
----
-
-## Why This Happens
-
-**Streamlit's Static File Serving:**
-
-- Streamlit only serves files from:
-  - `/.streamlit/static/` (internal Streamlit assets)
-  - Component assets via `declare_component()`
-  - NOT from arbitrary `battlewords/static/` directories
-
-- On HuggingFace Spaces:
-  - `/app/static/` is mapped by HF infrastructure
-  - Files in `battlewords/static/` are accessible at `/app/static/`
-  - ✅ PWA works perfectly
-
-- On localhost:
-  - No `/app/static/` mapping exists
-  - Streamlit returns HTML for all unrecognized paths
-  - ❌ PWA files return 404
-
----
-
-## How to Test PWA Locally
-
-### Option 1: Use ngrok (HTTPS Tunnel) ⭐ **RECOMMENDED**
-
-This is the **best way** to test PWA locally with full functionality:
-
-```bash
-# Terminal 1: Run Streamlit
-streamlit run app.py
-
-# Terminal 2: Expose with HTTPS
-ngrok http 8501
-
-# Output shows:
-# Forwarding https://abc123.ngrok-free.app -> http://localhost:8501
-```
-
-**Then visit the HTTPS URL on your phone or desktop:**
-- ✅ Full PWA functionality
-- ✅ Install prompt appears
-- ✅ manifest.json loads
-- ✅ Service worker registers
-- ✅ Icons display correctly
-
-**ngrok Setup:**
-1. Download: https://ngrok.com/download
-2. Sign up for free account
-3. Install: `unzip /path/to/ngrok.zip` (or chocolatey on Windows: `choco install ngrok`)
-4. Authenticate: `ngrok config add-authtoken <your-token>`
-5. Run: `ngrok http 8501`
-
----
-
-### Option 2: Deploy to HuggingFace Spaces ⭐ **PRODUCTION**
-
-PWA works out-of-the-box on HF Spaces:
-
-```bash
-git add battlewords/static/ battlewords/ui.py
-git commit -m "Add PWA support"
-git push
-
-# HF Spaces auto-deploys
-# Visit: https://surn-battlewords.hf.space
-```
-
-**Then test PWA:**
-- Android Chrome: "Add to Home Screen" prompt appears
-- iOS Safari: Share → "Add to Home Screen"
-- Desktop Chrome: Install icon in address bar
-
-✅ **This is where PWA is meant to work!**
-
----
-
-###Option 3: Manual Static File Server (Advanced)
-
-You can serve the static files separately:
-
-```bash
-# Terminal 1: Run Streamlit
-streamlit run app.py
-
-# Terminal 2: Serve static files
-cd battlewords/static
-python3 -m http.server 8502
-
-# Then access:
-# Streamlit: http://localhost:8501
-# Static files: http://localhost:8502/manifest.json
-```
-
-**Then modify the PWA paths in `ui.py`:**
-```python
-pwa_meta_tags = """
-<link rel="manifest" href="http://localhost:8502/manifest.json">
-<link rel="apple-touch-icon" href="http://localhost:8502/icon-192.png">
-<!-- etc -->
-"""
-```
-
-❌ **Not recommended**: Too complex, defeats the purpose
-
----
-
-## What About Challenge Mode?
-
-**Question:** "I loaded `localhost:8501/?game_id=hDjsB_dl` but don't see anything"
-
-**Answer:** Challenge Mode is **separate from PWA**. You should see a blue banner at the top if:
-
-### ✅ Requirements for Challenge Mode to Work:
-
-1. **Environment variables configured** (`.env` file):
-   ```bash
-   HF_API_TOKEN=hf_xxxxxxxxxxxxx
-   HF_REPO_ID=Surn/Storage
-   SPACE_NAME=Surn/BattleWords
-   ```
-
-2. **Valid game_id exists** in the HF repo:
-   - `hDjsB_dl` must be a real challenge created previously
-   - Check HuggingFace dataset repo: https://huggingface.co/datasets/Surn/Storage
-   - Look for: `games/<uid>/settings.json`
-   - Verify `shortener.json` has entry for `hDjsB_dl`
-
-3. **Internet connection** (to fetch challenge data)
-
-### If Challenge Mode ISN'T Working:
-
-**Check browser console (F12 → Console):**
-```javascript
-// Look for errors:
-"[game_storage] Could not resolve sid: hDjsB_dl"  ← Challenge not found
-"Failed to load game from sid"                     ← HF API error
-"HF_API_TOKEN not configured"                      ← Missing credentials
-```
-
-**If you see errors:**
-1. Verify `.env` file exists with correct variables
-2. Restart Streamlit (`Ctrl+C` and `streamlit run app.py` again)
-3. Try a different `game_id` from a known challenge
-4. Check HF repo has the challenge data
-
----
-
-## Summary Table
-
-| Feature | Localhost | Localhost + ngrok | HF Spaces (Production) |
-|---------|-----------|-------------------|------------------------|
-| **Game works** | ✅ | ✅ | ✅ |
-| **Challenge Mode** | ✅ (if .env configured) | ✅ | ✅ |
-| **PWA manifest loads** | ❌ | ✅ | ✅ |
-| **Service worker registers** | ❌ | ✅ | ✅ |
-| **Install prompt** | ❌ | ✅ | ✅ |
-| **Icons display** | ❌ | ✅ | ✅ |
-| **Full-screen mode** | ❌ | ✅ | ✅ |
-
----
-
-## What You Should Do
-
-### For Development:
-✅ **Just develop normally on localhost**
-- Game features work fine
-- Challenge Mode works (if .env configured)
-- PWA features won't work, but that's okay
-- Test PWA when you deploy
-
-### For PWA Testing:
-✅ **Use ngrok for quick local PWA testing**
-- 5 minutes to setup
-- Full PWA functionality
-- Test on real phone
-
-### For Production:
-✅ **Deploy to HuggingFace Spaces**
-- PWA works automatically
-- No configuration needed
-- `/app/static/` path works out-of-the-box
-
----
-
-## Bottom Line
-
-**Your question:** "Should I see something at the bottom of the screen?"
-
-**Answer:**
-
-1. **PWA install prompt**: ❌ Not on `localhost:8501` (Streamlit limitation)
-   - **Will work** on HF Spaces production deployment ✅
-   - **Will work** with ngrok HTTPS tunnel ✅
-
-2. **Challenge Mode banner**: ✅ Should appear at TOP (not bottom)
-   - Check if `?game_id=hDjsB_dl` exists in your HF repo
-   - Check browser console for errors
-   - Verify `.env` has `HF_API_TOKEN` configured
-
-The PWA implementation is **correct** and **ready for production**. It just won't work on bare localhost due to Streamlit's static file serving limitations. Once you deploy to HuggingFace Spaces, everything will work perfectly!
-
----
-
-## Quick Test Command
-
-```bash
-# Check if .env is configured:
-cat .env | grep HF_
-
-# Should show:
-# HF_API_TOKEN=hf_xxxxx
-# HF_REPO_ID=Surn/Storage
-# SPACE_NAME=Surn/BattleWords
-
-# If missing, Challenge Mode won't work locally
-```
-
----
-
-**Next Steps:**
-1. Test game functionality on localhost ✅
-2. Deploy to HF Spaces for PWA testing ✅
-3. Or install ngrok for local PWA testing ✅

PWA_INSTALL_GUIDE.mdx

@@ -1,208 +0,0 @@
-# BattleWords PWA Installation Guide
-
-BattleWords can now be installed as a Progressive Web App (PWA) on your mobile device or desktop, giving you a native app experience directly from your browser!
-
-## What is a PWA?
-
-A Progressive Web App allows you to:
-- ✅ Install BattleWords on your home screen (Android/iOS)
-- ✅ Run in full-screen mode without browser UI
-- ✅ Access the app quickly from your app drawer
-- ✅ Get automatic updates (always the latest version)
-- ✅ Basic offline functionality (cached assets)
-
-## Installation Instructions
-
-### Android (Chrome, Edge, Samsung Internet)
-
-1. **Visit the app**: Open https://surn-battlewords.hf.space in Chrome
-2. **Look for the install prompt**: A banner will appear at the bottom saying "Add BattleWords to Home screen"
-3. **Tap "Add"** or **"Install"**
-4. **Alternative method** (if no prompt):
-   - Tap the **three-dot menu** (⋮) in the top-right
-   - Select **"Install app"** or **"Add to Home screen"**
-   - Tap **"Install"**
-5. **Launch**: Find the BattleWords icon on your home screen and tap to open!
-
-**Result**: The app opens full-screen without the browser address bar, just like a native app.
-
----
-
-### iOS (Safari)
-
-**Note**: iOS requires using Safari browser (Chrome/Firefox won't work for PWA installation)
-
-1. **Visit the app**: Open https://surn-battlewords.hf.space in Safari
-2. **Tap the Share button**: The square with an arrow pointing up (at the bottom of the screen)
-3. **Scroll down** and tap **"Add to Home Screen"**
-4. **Edit the name** (optional): You can rename it from "BattleWords" if desired
-5. **Tap "Add"** in the top-right corner
-6. **Launch**: Find the BattleWords icon on your home screen and tap to open!
-
-**Result**: The app opens in standalone mode, similar to a native iOS app.
-
----
-
-### Desktop (Chrome, Edge, Brave)
-
-1. **Visit the app**: Open https://surn-battlewords.hf.space
-2. **Look for the install icon**:
-   - Chrome/Edge: Click the **install icon** (⊕) in the address bar
-   - Or click the **three-dot menu** → **"Install BattleWords"**
-3. **Click "Install"** in the confirmation dialog
-4. **Launch**:
-   - Windows: Find BattleWords in Start Menu or Desktop
-   - Mac: Find BattleWords in Applications folder
-   - Linux: Find in application launcher
-
-**Result**: BattleWords opens in its own window, separate from your browser.
-
----
-
-## Features of the PWA
-
-### Works Immediately ✅
-- Full game functionality (reveal cells, guess words, scoring)
-- Challenge Mode (create and play shared challenges)
-- Sound effects and background music
-- Ocean-themed animated background
-- All current features preserved
-
-### Offline Support 🌐
-- App shell cached for faster loading
-- Icons and static assets available offline
-- **Note**: Challenge Mode requires internet connection (needs to fetch/save from HuggingFace)
-
-### Updates 🔄
-- Automatic updates when you open the app
-- Always get the latest features and bug fixes
-- No manual update process needed
-
-### Privacy & Security 🔒
-- No new data collection (same as web version)
-- Environment variables stay on server (never exposed to PWA)
-- Service worker only caches public assets
-- All game data in Challenge Mode handled server-side
-
----
-
-## Uninstalling the PWA
-
-### Android
-1. Long-press the BattleWords icon
-2. Tap "Uninstall" or drag to "Remove"
-
-### iOS
-1. Long-press the BattleWords icon
-2. Tap "Remove App"
-3. Confirm "Delete App"
-
-### Desktop
-- **Chrome/Edge**: Go to `chrome://apps` or `edge://apps`, right-click BattleWords, select "Uninstall"
-- **Windows**: Settings → Apps → BattleWords → Uninstall
-- **Mac**: Delete from Applications folder
-
----
-
-## Troubleshooting
-
-### "Install" option doesn't appear
-- **Android**: Make sure you're using Chrome, Edge, or Samsung Internet (not Firefox)
-- **iOS**: Must use Safari browser
-- **Desktop**: Check if you're using a supported browser (Chrome, Edge, Brave)
-- Try refreshing the page (the install prompt may take a moment to appear)
-
-### App won't open after installation
-- Try uninstalling and reinstalling
-- Clear browser cache and try again
-- Make sure you have internet connection for first launch
-
-### Service worker errors in console
-- This is normal during development
-- The app will still function without the service worker
-- Full offline support requires the service worker to register successfully
-
-### Icons don't show up correctly
-- Wait a moment after installation (icons may take time to download)
-- Try force-refreshing the PWA (close and reopen)
-
----
-
-## Technical Details
-
-### Files Added for PWA Support
-
-```
-battlewords/
-├── static/
-│   ├── manifest.json          # PWA configuration
-│   ├── service-worker.js      # Offline caching logic
-│   ├── icon-192.png          # App icon (small)
-│   └── icon-512.png          # App icon (large)
-└── ui.py                     # Added PWA meta tags
-```
-
-### What's Cached Offline
-
-- App shell (HTML structure)
-- Icons (192x192, 512x512)
-- Manifest file
-- Previous game states (if you were playing before going offline)
-
-### What Requires Internet
-
-- Creating new challenges
-- Submitting results to leaderboards
-- Loading shared challenges
-- Downloading word lists (first time)
-- Fetching game updates
-
----
-
-## Comparison: PWA vs Native App
-
-| Feature | PWA | Native App |
-|---------|-----|------------|
-| Installation | Quick (1 tap) | Slow (app store) |
-| Size | ~5-10 MB | ~15-30 MB |
-| Updates | Automatic | Manual |
-| Platform support | Android, iOS, Desktop | Separate builds |
-| Offline mode | Partial | Full |
-| Performance | 90% of native | 100% |
-| App store presence | No | Yes |
-| Development time | 2-4 hours ✅ | 40-60 hours per platform |
-
----
-
-## Feedback
-
-If you encounter issues installing or using the PWA, please:
-1. Check the browser console for errors (F12 → Console tab)
-2. Report issues at: https://github.com/Oncorporation/BattleWords/issues
-3. Include: Device type, OS version, browser version, and error messages
-
----
-
-## For Developers
-
-To regenerate the PWA icons:
-```bash
-python3 generate_pwa_icons.py
-```
-
-To modify PWA behavior:
-- Edit `battlewords/static/manifest.json` (app metadata)
-- Edit `battlewords/static/service-worker.js` (caching logic)
-- Edit `battlewords/ui.py` (PWA meta tags, lines 34-86)
-
-To test PWA locally:
-```bash
-streamlit run app.py
-# Open http://localhost:8501 in Chrome
-# Chrome DevTools → Application → Manifest (verify manifest.json loads)
-# Chrome DevTools → Application → Service Workers (verify registration)
-```
-
----
-
-**Enjoy BattleWords as a native-like app experience! 🎮🌊**

README.md

@@ -19,22 +19,19 @@ tags:
 
 > **This project is used by [huggingface.co](https://huggingface.co/spaces/Surn/BattleWords) as a demonstration of interactive word games in Python.**
 
-**Current Version:** 0.2.37
-**Last Updated:** 2026-02-10
+**Current Version:** 0.2.37 BASIC
+**Branch:** `basic`
+**Last Updated:** 2026-02-11
 
 BattleWords is a vocabulary learning game inspired by classic Battleship mechanics. The objective is to discover hidden words on a grid, earning points for strategic guessing before all letters are revealed.
 
 ## Recent Changes
-- version 0.2.37
-- Footer navigation uses query-parameter links (`?page=play|leaderboard|settings`) via custom footer links
-- In-game "New Game" button behavior is now navigation-style (rerun) rather than a full session reset
-- Game over flow continues to support integrated challenge submission and optional share-link visibility
-
-- version 0.2.36
-- Added `user_id` and `subscription_level` to game state/results for user-specific features
-- Expanded `game_mode` options (includes `easy`)
-- UI polish: improved guess input styling (placeholder, typography) and layout tweaks (dialog/footer)
-- Conditional rendering for subscription-based features (difficulty and timer display)
+- version 0.2.37 (basic)
+  - Basic branch scope enforced: single play experience only
+  - No query-param routing, no footer navigation, no sidebar
+  - Challenge mode / share links / remote storage removed
+  - PWA support removed
+  - No audio system
 
 
 ## Features
@@ -50,57 +47,17 @@ BattleWords is a vocabulary learning game inspired by classic Battleship mechani
 - 10 incorrect guess limit per game
 - Two game modes: Classic (chain guesses) and Too Easy (single guess per reveal)
 
-### Audio & Visuals
+### Visuals
 - Ocean-themed gradient background with wave animations
-- Background music system (toggleable with volume control)
-- Sound effects for hits, misses, correct/incorrect guesses
 - Responsive UI built with Streamlit
 
-### Customization
+### Word lists
 - Multiple word lists (classic, fourth_grade, wordlist)
-- Wordlist controls (picker + sort/filter)
-- Configurable word spacing (0-2 cells between words)
-- Audio volume controls (music and effects separate)
-
-### ✅ Challenge Mode (v0.2.20+)
-- **Shareable challenge links** via short URLs (`?game_id=<sid>`)
-- **Multi-user leaderboards** sorted by score and time
-- **Remote storage** via Hugging Face datasets
-- **Word list difficulty calculation** and display
-- **Submit results** to existing challenges or create new ones
-- **Top 5 leaderboard** display in Challenge Mode banner
-- **"Show Challenge Share Links" toggle** (default OFF) to control URL visibility
-- Each player gets different random words from the same wordlist
-
-### UI & Navigation Updates (v0.2.35+)
-- **Spinner implementation** for loading states
-- **Updated graphics** for improved visuals
-- **Favicon** added for browser tab branding
-- **Footer navigation** links to Leaderboard, Play, and Settings pages (not sidebar)
-- **Leaderboard navigation** is now in the footer menu
-- **Leaderboard page routing** uses query parameters and custom navigation links
-- **Game over dialog** integrates leaderboard submission and displays qualification results
-- **Leaderboard page routing** uses query parameters and custom navigation links
-- **Game over dialog** integrates leaderboard submission and displays qualification results
+- Word lists are loaded locally from `battlewords/words/`
 
 ### Deployment & Technical
 - **Dockerfile-based deployment** supported for Hugging Face Spaces and other container platforms
-- **Environment variables** for Challenge Mode (HF_API_TOKEN, HF_REPO_ID, SPACE_NAME)
-- Works offline without HF credentials (Challenge Mode features disabled gracefully)
-
-### Progressive Web App (PWA) - v0.2.28
-- Installable on desktop and mobile from your browser:
-  - Chrome/Edge: Menu → “Install app”
-  - Android Chrome: “Add to Home screen”
-  - iOS Safari: Share → “Add to Home Screen”
-- Includes `service worker` and `manifest.json` with basic offline caching of static assets
-- See `INSTALL_GUIDE.md` for platform-specific steps
-
-### Planned (v0.3.0)
-- Local persistent storage for personal game history
-- Personal high scores sidebar (offline-capable)
-- Player statistics tracking
-- Deterministic seed UI for custom puzzles
+- No special environment variables required
 
 ### Beta (v0.5.0)
 - Word overlaps on shared letters (crossword-style)
@@ -113,10 +70,6 @@ BattleWords is a vocabulary learning game inspired by classic Battleship mechani
 - Multiple difficulty levels
 - Internationalization (i18n) support
 
-## Challenge Mode & Leaderboard
-
-When playing a shared challenge (via a `game_id` link), the leaderboard displays all submitted results for that challenge. The leaderboard is **sorted by highest score (descending), then by fastest time (ascending)**. This means players with the most points appear at the top, and ties are broken by the shortest completion time.
-
 ## Installation
 1. Clone the repository:
  ```
@@ -162,26 +115,8 @@ docker build -t battlewords .
 docker run -p8501:8501 battlewords
 ```
 
-### Environment Variables (for Challenge Mode)
-
-Challenge Mode requires a `.env` file in the project root with HuggingFace Hub credentials:
-
-```bash
-# Required for Challenge Mode
-HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx  # or HF_TOKEN
-HF_REPO_ID=YourUsername/YourRepo       # Target HF dataset repo
-SPACE_NAME=YourUsername/BattleWords    # 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_...`
-
-**Note:** The app works without these variables, but Challenge Mode features (sharing, leaderboards) will be disabled.
+### Environment Variables
+None required.
 
 ## Folder Structure
 
@@ -192,12 +127,8 @@ CRYPTO_PK=                             # Reserved for future signing
  - `generator.py` – word placement logic
  - `logic.py` – game mechanics (reveal, guess, scoring)
  - `ui.py` – Streamlit UI composition
- - `game_storage.py` – Hugging Face remote storage integration and challenge sharing
- - `local_storage.py` – local JSON storage for results and high scores
- - `storage.py` – (legacy) local storage and high scores
  - `words/wordlist.txt` – candidate words
-- `specs/` – documentation (`specs.md`, `requirements.md`)
-- `tests/` – unit tests
+- `specs/` – documentation (`specs/specs.mdx`, `specs/requirements.mdx`)
 
 ## How to Play
 
@@ -205,251 +136,15 @@ CRYPTO_PK=                             # Reserved for future signing
 2. After revealing a letter, enter a guess for a word in the text box.
 3. Earn points for correct guesses and bonus points for unrevealed letters.
 4. **The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.**
-5. **To play a shared challenge, use a link with `?game_id=<sid>`. Your result will be added to the challenge leaderboard.**
+5. Start a new run with **New Game**.
 
 ## Changelog
 
-### v0.3.0 (planned)
- - Local persistent storage for personal game history (offline-capable)
- - Personal high scores sidebar with filtering
- - Player statistics tracking (games played, averages, bests)
-
- - version 0.2.37
-  - Footer navigation uses query-parameter links (Play/Leaderboard/Settings)
-  - Play navigation behaves like a route change (query param) rather than invoking the New Game reset callback
- 
- - version 0.2.36
-  - Added `user_id` and `subscription_level` to game state/results for user-specific features
-  - Expanded `game_mode` options (includes `easy`)
-  - UI polish: improved guess input styling (placeholder, typography) and layout tweaks (dialog/footer)
-  - Conditional rendering for subscription-based features (difficulty and timer display)
-
- - version 0.2.35
-  - New spinner implementation for loading states
-  - Updated graphics and improved visual polish
-  - Favicon added for browser tab branding
-  - Leaderboard navigation moved to footer menu (not sidebar)
-  - Game over dialog integrates leaderboard submission and displays qualification results
-  - Leaderboard page routing uses query parameters and custom navigation links
-  - Footer navigation links to Leaderboard, Play, and Settings pages
-  - Minimal documentation and UI updates for these changes
-
-  > For the detailed porting checklist (Wrdler → BattleWords), see `specs/upgrade.mdx`.
- 
- - 0.2.33
-  - Simplified UI and improved gameplay experience
-  - Enhanced subheader text clarity
-  - Refined radar animation for smoother visuals
-  - Disabled guess input when appropriate
-  - Removed timer display
-  - Hid leaderboard and settings footer links
-  - Integrated game-over flow with score submission
-  - Improved styling for cleaner, faster transitions
-  
--0.2.32
- - updated .md spec files to .mdx
- 
--0.2.31
- - Updated README.md with new Streamlit SDK (1.52.1) and Python (3.12.8).
- - Incremented version to 0.2.31 in `__init__.py` and `pyproject.toml`.
- - Enhanced `audio.py` with error handling and smoother playback.
- - Added `validate_puzzle` and `filter_word_file` functions in `generator.py`.
- - Introduced new constants and `load_settings` in `constants.py`.
- - Improved settings page with wordlist controls and audio settings.
- - Refined UI in `ui.py` with compact layouts and performance optimizations.
- - Modularized helpers in `ui_helpers.py` and reintroduced PWA support.
-
--0.2.29
- - change difficulty calculation 
- - add test_compare_difficulty_functions
- - streamlit version update to 1.51.0
- 
--0.2.28
- - PWA INSTALL_GUIDE.md added
- - PWA implementation with service worker and manifest.json added
- - Footer navigation links to Leaderboard, Play, and Settings pages
- - Leaderboard navigation moved to footer menu (not sidebar)
- - Leaderboard page routing uses query parameters and custom navigation links
- - Game over dialog integrates leaderboard submission and displays qualification results
-
--0.2.27
- - Add "Show Challenge Share Links" setting (default: off)
- - When disabled:
-   - Header Challenge Mode: hides the Share Challenge link
-   - Game Over: allows submitting results but suppresses displaying the generated share URL
- - The setting is saved in session state and preserved across "New Game"
- - No changes to game logic or storage; only UI visibility behavior
- 
--0.2.26
-  - fix copy/share link button
-  
--0.2.25
- - Share challenge from expander
- - fix incorrect guess overlap of guess box 
- 
--0.2.24
- - compress height
- - change incorrect guess tooltip location
- - update final screen layout
- - add word difficulty formula
- - update documentation
-
--0.2.23
- - Update miss and correct guess sound effects to new versions
- - allow iframe hosted version to pass url as a query string parameter (&iframe_host=https%3A%2F%2Fwww.battlewords.com%2Fplaynow.html) url encoding is required.
- - minimal security added to prevent users from changing the options in a challenge.
-
--0.2.22
- - fix challenge mode link 
- - challenge mode UI improvements
- 
--0.2.21
- - fix tests 
- 
--0.2.20 
- - Remote Storage game_id:
-   - Per-game JSON settings uploaded to a storage server (Hugging Face repo) under unique `games/{uid}/settings.json`
-   - A shortened URL id (sid) is generated; shareable link: `?game_id=<sid>`
-   - On load with `game_id`, the app resolves sid to the JSON and applies word_list, game_mode, grid_size, puzzle options
- - High Scores: add remote `highscores/highscores.json` (repo) alongside local highscores
- - Dependencies: add `huggingface_hub` and `python-dotenv`
- - Env: `.env` should include `HF_API_TOKEN` (or `HF_TOKEN`), `CRYPTO_PK`, `HF_REPO_ID`, `SPACE_NAME`
+- version 0.2.37 (basic)
+  - Removed Challenge Mode / Share Links / Remote Storage (HF)
+  - Removed PWA support
+  - Documentation trimmed to basic branch scope
 
-### Environment Variables
-- HF_API_TOKEN or HF_TOKEN: HF Hub access token
-- CRYPTO_PK: reserved for signing (optional)
-- HF_REPO_ID: e.g., Surn/Storage
-- SPACE_NAME: e.g., Surn/BattleWords
-
-### Remote Storage Structure
-- shortener.json
-- games/{uid}/settings.json
-- highscores/highscores.json
-
-Note
-- `battlewords/storage.py` remains local-only storage; a separate HF integration wrapper is provided as `game_storage.py` for remote challenge mode.
-
--0.2.19
-  - Fix music and sound effect volume issues 
-  - Update documentation for proposed new features
-
--0.2.18
- - Fix sound effect volume wiring and apply volume to all effects (hit/miss/correct/incorrect)
- - Respect "Enable music" and "Volume" when playing congratulations music and when resuming background music (uses selected track)
- - Add "Enable Sound Effects" checkbox (on by default) and honor it across the app
- - Save generated effects to `assets/audio/effects/` so they are picked up by the app
- - Add `requests` dependency for sound effect generation
- 
--0.2.17
- - documentation updates and corrections
- - updated CLAUDE.md with accurate feature status and project structure
- - clarified v0.3.0 planned features vs current implementation
-
--0.2.16
- - replace question marks in score panel with underscores
- - add option to toggle incorrect guess history display in settings (enabled by default)
- - game over popup updated to ensure it is fully visible on screen
- 
--0.2.15
- - fix music playing after game end
- - change incorrect guesses icon
- - fix sound effect and music volume issues
- 
--0.2.14
- - bug fix on final score popup
- - score panel alignment centered
- - change incorrect guess history UI
-
--0.2.13
- - upgrade background ocean view 
- - apply volume control to sound effects
-
--0.2.12
- - fix music looping on congratulations screen
-
--0.2.11
- - update timer to be live during gameplay, but reset with each action
- - compact design
- - remove fullscreen image tooltip
-
--0.2.10
- - reduce sonar graphic size
- - update music and special effects file locations
- - remove some music and sound effects
- - change Guess Text input color
- - incorrect guess UI update
- - scoreboard update
-
--0.2.9
- - fix sonar grid alignment issue on some browsers
- - When all letters of a word are revealed, it is automatically marked as found.
-
--0.2.8
- - Add10 incorrect guess limit per game
-
--0.2.7
- - fix background music playback issue on some browsers
- - add sound effects
- - enhance sonar grid visualization
- - add claude.md documentation
- 
--0.2.6
- - fix sonar grid alignment
- - improve score summary layout and styling
- - Add timer to game display in sidebar
-
--0.2.5
- - fix finale pop up issue
- - make grid cells square on wider devices
-
--0.2.4
- - Add music files to repo
- - disable music by default 
-
--0.2.3
- - Update version information display
- - adjust sonar grid alignment
- - fix settings scroll issue 
- 
--0.2.2
- - Add Musical background and settings to toggle sound on/off.
-
--0.2.1
- - Add Theme toggle (light/dark/custom) in sidebar.
-
--0.2.0
- - Added a loading screen when starting a new game.
- - Added a congratulations screen with your final score and tier when the game ends.
- 
--0.1.13 
- - Improved score summary layout for clarity and style.
-
--0.1.12
- - Improved score summary layout and styling.
- - Enhanced overall appearance and readability.
-
--0.1.11
- - Game now ends when all words are found or revealed.
- - Added word spacing logic and improved settings.
-
--0.1.10
- - Added game mode selector and improved UI feedback.
-
--0.1.9
- - Improved background and mobile layout.
-
--0.1.8
- - Updated to Python3.12.
-
--0.1.5
- - Added hit/miss indicator and improved grid feedback.
-
--0.1.4
- - Radar visualization improved and mobile layout enhanced.
-
--0.1.3
- - Added wordlist picker and sort feature.
- - Improved score panel and final score display.
 
 ## Known Issues / TODO
 
@@ -514,95 +209,4 @@ Spaces can be embedded in other sites using an `<iframe>`:
 
 For full configuration options, see [Spaces Config Reference](https://huggingface.co/docs/hub/spaces-config-reference) and [Streamlit SDK Guide](https://huggingface.co/docs/hub/spaces-sdks-streamlit).
 
-# Assets Setup
-
-To fully experience BattleWords, especially the audio elements, ensure you set up the following assets:
-
-- Place your background music `.mp3` files in `battlewords/assets/audio/music/` to enable music.
-- Place your sound effect files (`.mp3` or `.wav`) in `battlewords/assets/audio/effects/` for sound effects.
-
-Refer to the documentation for guidance on compatible audio formats and common troubleshooting tips.
-
-# Sound Asset Generation
-
-To generate and save custom sound effects for BattleWords, you can use the `generate_sound_effect` function.
-
-## Function: `generate_sound_effect`
-
-```python
-def generate_sound_effect(effect: str, save_to_assets: bool = False, use_api: str = "huggingface") -> str:
- """
- Generate a sound effect and save it as a file.
-
- Parameters:
- - `effect`: Name of the effect to generate.
- - `save_to_assets`: If `True`, saves the effect to the assets directory; 
- if `False`, saves to a temporary location. Default is `False`.
- - `use_api`: API to use for generation. Options are "huggingface" or "replicate". Default is "huggingface".
-
- Returns:
- - File path to the saved sound effect.
- ```
-
-## Parameters
-
-- `effect`: The name of the sound effect you want to generate (e.g., "explosion", "powerup").
-- `save_to_assets` (optional): Set to `True` to save the generated sound effect to the game's assets directory. If `False`, the effect is saved to a temporary location. Default is `False`.
-- `use_api` (optional): The API to use for generating the sound. Options are `"huggingface"` or `"replicate"`. Default is `"huggingface"`.
-
-## Returns
-
-- The function returns the file path to the saved sound effect, whether it's in the assets directory or a temporary location.
-
-## Usage Example
-
-To generate a sound effect and save it to the assets directory:
-
-```python
-generate_sound_effect("your_effect_name", save_to_assets=True)
-```
-
-To generate a sound effect and keep it in a temporary location:
-
-```python
-temp_path = generate_sound_effect("your_effect_name", save_to_assets=False)
-```
-
-## Note
-
-Ensure you have the necessary permissions and API access (if required) to use the sound generation service. Generated sounds are subject to the terms of use of the respective API.
-
-For any issues or enhancements, please refer to the project documentation or contact the project maintainer.
-
-Happy gaming and sound designing!
-
-## What's New in v0.2.20-0.2.27: Challenge Mode 🎯
-
-### Remote Challenge Sharing 🔗
-- Share challenges with friends via short URLs (`?game_id=<sid>`)
-- Each player gets different random words from the same wordlist
-- Multi-user leaderboards sorted by score and time
-- Word list difficulty calculation and display
-- Compare your performance against others!
-
-### Leaderboards 🏆
-- Top 5 players displayed in Challenge Mode banner
-- Results sorted by: highest score → fastest time → highest difficulty
-- Submit results to existing challenges or create new ones
-- Player names supported (optional, defaults to "Anonymous")
-
-### Remote Storage 💾
-- Challenge data stored in Hugging Face dataset repositories
-- Automatic save on game completion (with user consent)
-- "Show Challenge Share Links" toggle for privacy control (default OFF)
-- Works offline when HF credentials not configured
-
-## What's Planned for v0.3.0
-
-### Local Player History (Coming Soon)
-- Personal game results saved locally in `~/.battlewords/data/`
-- Offline-capable high score tracking
-- Player statistics (games played, averages, bests)
-- Privacy-first: no cloud dependency for personal data
-- Easy data management (delete `~/.battlewords/data/` to reset)
 

battlewords/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "0.2.37"
-__all__ = ["models", "generator", "logic", "ui", "game_storage", "modules"]
+__version__ = "0.2.37 BASIC"
+__all__ = ["models", "generator", "logic", "ui", "modules"]

battlewords/game_storage.py

@@ -1,581 +0,0 @@
-# file: battlewords/game_storage.py
-"""
-BattleWords-specific storage wrapper for HuggingFace storage operations.
-
-This module provides high-level functions for saving and loading BattleWords games
-using the shared storage module from battlewords.modules.
-"""
-__version__ = "0.1.3"
-
-import json
-import tempfile
-import os
-from datetime import datetime, timezone
-from typing import Dict, Any, List, Optional, Tuple
-import logging
-from urllib.parse import unquote
-
-from battlewords.modules import (
-    upload_files_to_repo,
-    gen_full_url,
-    HF_REPO_ID,
-    SHORTENER_JSON_FILE,
-    SPACE_NAME,
-    _list_repo_folders,
-    _list_repo_files_in_folder
-)
-from battlewords.modules.storage import _get_json_from_repo
-from battlewords.local_storage import save_json_to_file
-from battlewords.word_loader import compute_word_difficulties
-
-# Configure logging
-logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
-logger = logging.getLogger(__name__)
-
-
-def list_hf_folders(path_prefix: str, repo_id: Optional[str] = None) -> List[str]:
-    """
-    List unique folders under a path in the HF repository.
-    Useful for folder-based discovery of leaderboards (e.g., discovery by date).
-
-    Args:
-        path_prefix: The prefix path to list folders under
-        repo_id: Optional HF repository ID (uses default if None)
-
-    Returns:
-        List[str]: Sorted list of folder names
-    """
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-    return _list_repo_folders(repo_id=repo_id, path_prefix=path_prefix)
-
-
-def list_hf_files(folder_path: str, repo_id: Optional[str] = None) -> List[str]:
-    """
-    List file names directly in a folder in the HF repository.
-
-    Args:
-        folder_path: The folder path to list files from
-        repo_id: Optional HF repository ID (uses default if None)
-
-    Returns:
-        List[str]: Sorted list of file names
-    """
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-    return _list_repo_files_in_folder(repo_id=repo_id, folder_path=folder_path)
-
-
-def generate_uid() -> str:
-    """
-    Generate a unique identifier for a game.
-
-    Format: YYYYMMDDTHHMMSSZ-RANDOM
-    Example: 20250123T153045Z-A7B9C2
-
-    Returns:
-        str: Unique game identifier
-    """
-    import random
-    import string
-
-    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
-    random_suffix = ''.join(random.choices(string.ascii_uppercase + string.digits, k=6))
-    return f"{timestamp}-{random_suffix}"
-
-
-def serialize_game_settings(
-    word_list: List[str],
-    username: str,
-    score: int,
-    time_seconds: int,
-    game_mode: str,
-    grid_size: int = 12,
-    spacer: int = 1,
-    may_overlap: bool = False,
-    wordlist_source: Optional[str] = None,
-    challenge_id: Optional[str] = None
-) -> Dict[str, Any]:
-    """
-    Serialize game settings into a JSON-compatible dictionary.
-    Creates initial structure with one user's result.
-    Each user has their own uid and word_list.
-
-    Args:
-        word_list: List of words used in THIS user's game
-        username: Player's name
-        score: Final score achieved
-        time_seconds: Time taken to complete (in seconds)
-        game_mode: Game mode ("classic" or "too_easy")
-        grid_size: Grid size (default: 12)
-        spacer: Word spacing configuration (0-2, default: 1)
-        may_overlap: Whether words can overlap (default: False)
-        wordlist_source: Source file name (e.g., "classic.txt")
-        challenge_id: Optional challenge ID (generated if not provided)
-
-    Returns:
-        dict: Serialized game settings with users array
-    """
-    if challenge_id is None:
-        challenge_id = generate_uid()
-
-    # Try compute difficulty using the source file; optional
-    difficulty_value: Optional[float] = None
-    try:
-        if wordlist_source:
-            words_dir = os.path.join(os.path.dirname(__file__), "words")
-            wordlist_path = os.path.join(words_dir, wordlist_source)
-            if os.path.exists(wordlist_path):
-                total_diff, _ = compute_word_difficulties(wordlist_path, words_array=word_list)
-                difficulty_value = float(total_diff)
-    except Exception as _e:
-        # optional field, swallow errors
-        difficulty_value = None
-
-    # Build user result with desired ordering: uid, username, word_list, word_list_difficulty, score, time, timestamp
-    user_result = {
-        "uid": generate_uid(),
-        "username": username,
-        "word_list": word_list,
-    }
-    if difficulty_value is not None:
-        user_result["word_list_difficulty"] = difficulty_value
-    user_result["score"] = score
-    user_result["time"] = time_seconds
-    user_result["timestamp"] = datetime.now(timezone.utc).isoformat()
-
-    settings = {
-        "challenge_id": challenge_id,
-        "game_mode": game_mode,
-        "grid_size": grid_size,
-        "puzzle_options": {
-            "spacer": spacer,
-            "may_overlap": may_overlap
-        },
-        "users": [user_result],
-        "created_at": datetime.now(timezone.utc).isoformat(),
-        "version": __version__
-    }
-
-    if wordlist_source:
-        settings["wordlist_source"] = wordlist_source
-
-    return settings
-
-
-def add_user_result_to_game(
-    sid: str,
-    username: str,
-    word_list: List[str],
-    score: int,
-    time_seconds: int,
-    repo_id: Optional[str] = None
-) -> bool:
-    """
-    Add a user's result to an existing shared challenge.
-    Each user gets their own uid and word_list.
-
-    Args:
-        sid: Short ID of the existing challenge
-        username: Player's name
-        word_list: List of words THIS user played
-        score: Score achieved
-        time_seconds: Time taken (seconds)
-        repo_id: HF repository ID (uses HF_REPO_ID from env if None)
-
-    Returns:
-        bool: True if successfully added, False otherwise
-    """
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-
-    logger.info(f"➕ Adding user result to challenge {sid}")
-
-    try:
-        # Load existing game settings
-        settings = load_game_from_sid(sid, repo_id)
-        if not settings:
-            logger.error(f"❌ Challenge not found: {sid}")
-            return False
-
-        # Compute optional difficulty using the saved wordlist_source if available
-        difficulty_value: Optional[float] = None
-        try:
-            wordlist_source = settings.get("wordlist_source")
-            if wordlist_source:
-                words_dir = os.path.join(os.path.dirname(__file__), "words")
-                wordlist_path = os.path.join(words_dir, wordlist_source)
-                if os.path.exists(wordlist_path):
-                    total_diff, _ = compute_word_difficulties(wordlist_path, words_array=word_list)
-                    difficulty_value = float(total_diff)
-        except Exception:
-            difficulty_value = None
-
-        # Create new user result with ordering and optional difficulty
-        user_result = {
-            "uid": generate_uid(),
-            "username": username,
-            "word_list": word_list,
-        }
-        if difficulty_value is not None:
-            user_result["word_list_difficulty"] = difficulty_value
-        user_result["score"] = score
-        user_result["time"] = time_seconds
-        user_result["timestamp"] = datetime.now(timezone.utc).isoformat()
-
-        # Add to users array
-        if "users" not in settings:
-            settings["users"] = []
-        settings["users"].append(user_result)
-
-        logger.info(f"👥 Now {len(settings['users'])} users in game")
-
-        # Get the file path from the sid
-        status, full_url = gen_full_url(
-            short_url=sid,
-            repo_id=repo_id,
-            json_file=SHORTENER_JSON_FILE
-        )
-
-        if status != "success_retrieved_full" or not full_url:
-            logger.error(f"❌ Could not resolve sid: {sid}")
-            return False
-
-        # Extract challenge_id from URL
-        url_parts = full_url.split("/resolve/main/")
-        if len(url_parts) != 2:
-            logger.error(f"❌ Invalid URL format: {full_url}")
-            return False
-
-        file_path = url_parts[1]  # e.g., "games/{challenge_id}/settings.json"
-        challenge_id = file_path.split("/")[1]  # Extract challenge_id
-        folder_name = f"games/{challenge_id}"
-
-        # Save updated settings back to HF
-        try:
-            with tempfile.TemporaryDirectory() as tmpdir:
-                settings_path = save_json_to_file(settings, tmpdir, "settings.json")
-                logger.info(f"📤 Updating {folder_name}/settings.json")
-
-                response = upload_files_to_repo(
-                    files=[settings_path],
-                    repo_id=repo_id,
-                    folder_name=folder_name,
-                    repo_type="dataset"
-                )
-
-            logger.info(f"✅ User result added for {username}")
-            return True
-
-        except Exception as e:
-            logger.error(f"❌ Failed to upload updated settings: {e}")
-            return False
-
-    except Exception as e:
-        logger.error(f"❌ Failed to add user result: {e}")
-        return False
-
-
-def save_game_to_hf(
-    word_list: List[str],
-    username: str,
-    score: int,
-    time_seconds: int,
-    game_mode: str,
-    grid_size: int = 12,
-    spacer: int = 1,
-    may_overlap: bool = False,
-    repo_id: Optional[str] = None,
-    wordlist_source: Optional[str] = None
-) -> Tuple[str, Optional[str], Optional[str]]:
-    """
-    Save game settings to HuggingFace repository and generate shareable URL.
-    Creates a new game entry with the first user's result.
-
-    This function:
-    1. Generates a unique UID for the game
-    2. Serializes game settings to JSON with first user
-    3. Uploads settings.json to HF repo under games/{uid}/
-    4. Creates a shortened URL (sid) for sharing
-    5. Returns the full URL and short ID
-
-    Args:
-        word_list: List of words used in the game
-        username: Player's name
-        score: Final score achieved
-        time_seconds: Time taken to complete (in seconds)
-        game_mode: Game mode ("classic" or "too_easy")
-        grid_size: Grid size (default: 12)
-        spacer: Word spacing configuration (0-2, default: 1)
-        may_overlap: Whether words can overlap (default: False)
-        repo_id: HF repository ID (uses HF_REPO_ID from env if None)
-        wordlist_source: Source wordlist file name (e.g., "classic.txt")
-
-    Returns:
-        tuple: (challenge_id, full_url, sid) where:
-            - challenge_id: Unique challenge identifier
-            - full_url: Full URL to settings.json
-            - sid: Shortened ID for sharing (8 characters)
-
-    Raises:
-        Exception: If upload or URL shortening fails
-
-    Example:
-        >>> uid, full_url, sid = save_game_to_hf(
-        ...     word_list=["WORD", "TEST", "GAME", "PLAY", "SCORE", "FINAL"],
-        ...     username="Alice",
-        ...     score=42,
-        ...     time_seconds=180,
-        ...     game_mode="classic",
-        ...     wordlist_source="classic.txt"
-        ... )
-        >>> print(f"Share: https://{SPACE_NAME}/?game_id={sid}")
-    """
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-
-    logger.info(f"💾 Saving game to HuggingFace repo: {repo_id}")
-
-    # Generate challenge ID and serialize settings
-    challenge_id = generate_uid()
-    settings = serialize_game_settings(
-        word_list=word_list,
-        username=username,
-        score=score,
-        time_seconds=time_seconds,
-        game_mode=game_mode,
-        grid_size=grid_size,
-        spacer=spacer,
-        may_overlap=may_overlap,
-        challenge_id=challenge_id,
-        wordlist_source=wordlist_source
-    )
-
-    logger.debug(f"🆔 Generated Challenge ID: {challenge_id}")
-
-    # Write settings to a temp directory using a fixed filename 'settings.json'
-    folder_name = f"games/{challenge_id}"
-    try:
-        with tempfile.TemporaryDirectory() as tmpdir:
-            settings_path = save_json_to_file(settings, tmpdir, "settings.json")
-            logger.info(f"📤 Uploading to {folder_name}/settings.json")
-            # Upload to HF repo under games/{uid}/settings.json
-            response = upload_files_to_repo(
-                files=[settings_path],
-                repo_id=repo_id,
-                folder_name=folder_name,
-                repo_type="dataset"
-            )
-
-        # Construct full URL to settings.json
-        full_url = f"https://huggingface.co/datasets/{repo_id}/resolve/main/{folder_name}/settings.json"
-        logger.info(f"✅ Uploaded: {full_url}")
-
-        # Generate short URL
-        logger.info("🔗 Creating short URL...")
-        status, sid = gen_full_url(
-            full_url=full_url,
-            repo_id=repo_id,
-            json_file=SHORTENER_JSON_FILE
-        )
-
-        if status in ["created_short", "success_retrieved_short", "exists_match"]:
-            logger.info(f"✅ Short ID created: {sid}")
-            share_url = f"https://{SPACE_NAME}/?game_id={sid}"
-            logger.info(f"🎮 Share URL: {share_url}")
-            return challenge_id, full_url, sid
-        else:
-            logger.warning(f"⚠️ URL shortening failed: {status}")
-            return challenge_id, full_url, None
-
-    except Exception as e:
-        logger.error(f"❌ Failed to save game: {e}")
-        raise
-
-
-def load_game_from_sid(
-    sid: str,
-    repo_id: Optional[str] = None
-) -> Optional[Dict[str, Any]]:
-    """
-    Load game settings from a short ID (sid).
-    If settings.json cannot be found, return None and allow normal game loading.
-
-    Args:
-        sid: Short ID (8 characters) from shareable URL
-        repo_id: HF repository ID (uses HF_REPO_ID from env if None)
-
-    Returns:
-        dict | None: Game settings or None if not found
-
-        dict: Challenge settings containing:
-            - challenge_id: Unique challenge identifier
-            - wordlist_source: Source wordlist file (e.g., "classic.txt")
-            - game_mode: Game mode
-            - grid_size: Grid size
-            - puzzle_options: Puzzle configuration (spacer, may_overlap)
-            - users: Array of user results, each with:
-                - uid: Unique user game identifier
-                - username: Player name
-                - word_list: Words THIS user played
-                - score: Score achieved
-                - time: Time taken (seconds)
-                - timestamp: When result was recorded
-            - created_at: When challenge was created
-            - version: Storage version
-
-        Returns None if sid not found or download fails
-
-    Example:
-        >>> settings = load_game_from_sid("abc12345")
-        >>> if settings:
-        ...     print(f"Challenge ID: {settings['challenge_id']}")
-        ...     print(f"Wordlist: {settings['wordlist_source']}")
-        ...     for user in settings['users']:
-        ...         print(f"{user['username']}: {user['score']} pts")
-    """
-    if repo_id is None:
-        repo_id = HF_REPO_ID
-
-    logger.info(f"🔍 Loading game from sid: {sid}")
-
-    try:
-        # Resolve sid to full URL
-        status, full_url = gen_full_url(
-            short_url=sid,
-            repo_id=repo_id,
-            json_file=SHORTENER_JSON_FILE
-        )
-
-        if status != "success_retrieved_full" or not full_url:
-            logger.warning(f"⚠️ Could not resolve sid: {sid} (status: {status})")
-            return None
-
-        logger.info(f"✅ Resolved to: {full_url}")
-
-        # Extract the file path from the full URL
-        # URL format: https://huggingface.co/datasets/{repo_id}/resolve/main/{path}
-        # We need just the path part: games/{uid}/settings.json
-        try:
-            url_parts = full_url.split("/resolve/main/")
-            if len(url_parts) != 2:
-                logger.error(f"❌ Invalid URL format: {full_url}")
-                return None
-            
-            file_path = url_parts[1]
-            logger.info(f"📥 Downloading {file_path} using authenticated API...")
-            
-            settings = _get_json_from_repo(repo_id, file_path, repo_type="dataset")
-            if not settings:
-                logger.error(f"❌ settings.json not found for sid: {sid}. Loading normal game.")
-                return None
-            
-            logger.info(f"✅ Loaded challenge: {settings.get('challenge_id', 'unknown')}")
-            users = settings.get('users', [])
-            logger.debug(f"Users in challenge: {len(users)}")
-
-            return settings
-
-        except Exception as e:
-            logger.error(f"❌ Failed to parse URL or download: {e}")
-            return None
-
-    except Exception as e:
-        logger.error(f"❌ Unexpected error loading game: {e}")
-        return None
-
-
-def get_shareable_url(sid: str, base_url: str = None) -> str:
-    """
-    Generate a shareable URL from a short ID.
-    If running locally, use localhost. Otherwise, use HuggingFace Space domain.
-    Additionally, if an "iframe_host" query parameter is present in the current
-    Streamlit request, it takes precedence and will be used as the base URL.
-
-    Args:
-        sid: Short ID (8 characters)
-        base_url: Optional override for the base URL (for testing or custom deployments)
-
-    Returns:
-        str: Full shareable URL
-
-    Example:
-        >>> url = get_shareable_url("abc12345")
-        >>> print(url)
-        https://surn-battlewords.hf.space/?game_id=abc12345
-    """
-    import os
-    from battlewords.modules.constants import SPACE_NAME
-
-    # 0) If not explicitly provided, try to read iframe_host from Streamlit query params
-    if base_url is None:
-        try:
-            import streamlit as st # local import to avoid hard dependency
-            params = getattr(st, "query_params", None)
-            if params is None and hasattr(st, "experimental_get_query_params"):
-                params = st.experimental_get_query_params()
-            if params and "iframe_host" in params:
-                raw_host = params.get("iframe_host")
-                # st.query_params may return str or list[str]
-                if isinstance(raw_host, (list, tuple)):
-                    raw_host = raw_host[0] if raw_host else None
-                if raw_host:
-                    decoded = unquote(str(raw_host))
-                    if decoded:
-                        base_url = decoded
-        except Exception:
-            # Ignore any errors here and fall back to defaults below
-            pass
-
-    # 1) If base_url is provided (either parameter or iframe_host), use it directly
-    if base_url:
-        sep = '&' if '?' in base_url else '?'
-        return f"{base_url}{sep}game_id={sid}"
-
-    if os.environ.get("IS_LOCAL", "true").lower() == "true":
-        # 2) Check for local development (common Streamlit env vars)
-        port = os.environ.get("PORT") or os.environ.get("STREAMLIT_SERVER_PORT") or "8501"
-        host = os.environ.get("HOST") or os.environ.get("STREAMLIT_SERVER_ADDRESS") or "localhost"
-        if host in ("localhost", "127.0.0.1") or os.environ.get("IS_LOCAL", "").lower() == "true":
-            return f"http://{host}:{port}/?game_id={sid}"
-
-    # 3) Otherwise, build HuggingFace Space URL from SPACE_NAME
-    space = (SPACE_NAME or "surn/battlewords").lower().replace("/", "-")
-    return f"https://{space}.hf.space/?game_id={sid}"
-
-
-if __name__ == "__main__":
-    # Example usage
-    print("BattleWords Game Storage Module")
-    print(f"Version: {__version__}")
-    print(f"Target Repository: {HF_REPO_ID}")
-    print(f"Space Name: {SPACE_NAME}")
-
-    # Example: Save a game
-    print("\n--- Example: Save Game ---")
-    try:
-        challenge_id, full_url, sid = save_game_to_hf(
-            word_list=["WORD", "TEST", "GAME", "PLAY", "SCORE", "FINAL"],
-            username="Alice",
-            score=42,
-            time_seconds=180,
-            game_mode="classic"
-        )
-        print(f"Challenge ID: {challenge_id}")
-        print(f"Full URL: {full_url}")
-        print(f"Short ID: {sid}")
-        print(f"Share: {get_shareable_url(sid)}")
-    except Exception as e:
-        print(f"Error: {e}")
-
-    # Example: Load a game
-    print("\n--- Example: Load Game ---")
-    if sid:
-        settings = load_game_from_sid(sid)
-        if settings:
-            print(f"Loaded Challenge: {settings['challenge_id']}")
-            print(f"Wordlist Source: {settings.get('wordlist_source', 'N/A')}")
-            users = settings.get('users', [])
-            print(f"Users: {len(users)}")
-            for user in users:
-                print(f"  - {user['username']}: {user['score']} pts in {user['time']}s")

battlewords/modules/__init__.py

@@ -6,26 +6,8 @@ These modules are imported from the OpenBadge project and provide
 reusable functionality for storage, constants, and file utilities.
 """
 
-from .storage import (
-    upload_files_to_repo,
-    gen_full_url,
-    generate_permalink,
-    generate_permalink_from_urls,
-    store_issuer_keypair,
-    get_issuer_keypair,
-    get_verification_methods_registry,
-    list_issuer_ids,
-    _list_repo_folders,
-    _list_repo_files_in_folder
-)
-
 from .constants import (
     APP_SETTINGS,
-    HF_API_TOKEN,
-    CRYPTO_PK,
-    HF_REPO_ID,
-    SPACE_NAME,
-    SHORTENER_JSON_FILE,
     MAX_DISPLAY_ENTRIES,
     TMPDIR,
     upload_file_types,
@@ -54,25 +36,8 @@ from .file_utils import (
 )
 
 __all__ = [
-    # storage.py
-    'upload_files_to_repo',
-    'gen_full_url',
-    'generate_permalink',
-    'generate_permalink_from_urls',
-    'store_issuer_keypair',
-    'get_issuer_keypair',
-    'get_verification_methods_registry',
-    'list_issuer_ids',
-    '_list_repo_folders',
-    '_list_repo_files_in_folder',
-
     # constants.py
     'APP_SETTINGS',
-    'HF_API_TOKEN',
-    'CRYPTO_PK',
-    'HF_REPO_ID',
-    'SPACE_NAME',
-    'SHORTENER_JSON_FILE',
     'MAX_DISPLAY_ENTRIES',
     'TMPDIR',
     'upload_file_types',

battlewords/modules/constants.py

@@ -1,7 +1,9 @@
 # battlewords/modules/constants.py
-"""
-Storage-related constants for BattleWords.
-Trimmed version of OpenBadge constants - only includes what's needed for storage.py
+"""battlewords/modules/constants.py
+
+Basic branch constants.
+
+Note: Hugging Face storage/challenge-mode constants were removed in the `basic` branch.
 """
 import os
 import json
@@ -9,20 +11,6 @@ import tempfile
 import logging
 from pathlib import Path
 from typing import Dict, Any
-from dotenv import load_dotenv
-
-# Load environment variables from .env file
-dotenv_path = Path(__file__).parent.parent.parent / '.env'
-load_dotenv(dotenv_path)
-
-# Hugging Face Configuration
-HF_API_TOKEN = os.getenv("HF_TOKEN", os.getenv("HF_API_TOKEN", None))
-CRYPTO_PK = os.getenv("CRYPTO_PK", None)
-
-# Repository Configuration
-HF_REPO_ID = os.getenv("HF_REPO_ID", "Surn/Storage")
-SPACE_NAME = os.getenv('SPACE_NAME', 'Surn/BattleWords')
-SHORTENER_JSON_FILE = "shortener.json"
 MAX_DISPLAY_ENTRIES = int(os.getenv("MAX_DISPLAY_ENTRIES", 25))
 
 # ---------------------------------------------------------------------------
@@ -50,7 +38,7 @@ def load_settings() -> Dict[str, Any]:
         # Display settings
         "show_incorrect_guesses": True,
         "enable_free_letters": False,
-        "show_challenge_links": True,
+        "show_challenge_links": False,
 
         # Game defaults
         "default_wordlist": "classic.txt",

battlewords/modules/storage.md

@@ -1,268 +0,0 @@
-# Storage Module (`modules/storage.py`) Usage Guide
-
-The `storage.py` module provides helper functions for:
-- Generating permalinks for 3D viewer projects.
-- Uploading files in batches to a Hugging Face repository.
-- Managing URL shortening by storing (short URL, full URL) pairs in a JSON file on the repository.
-- Retrieving full URLs from short URL IDs and vice versa.
-- Handle specific file types for 3D models, images, video and audio.
-- **📁 Listing folders and files in HuggingFace repositories.**
-- **🔑 Cryptographic key management for Open Badge 3.0 issuers.**
-
-## Key Functions
-
-### 1. `generate_permalink(valid_files, base_url_external, permalink_viewer_url="surn-3d-viewer.hf.space")`
-- **Purpose:**  
-  Given a list of file paths, it looks for exactly one model file (with an extension defined in `model_extensions`) and exactly two image files (extensions defined in `image_extensions`). If the criteria are met, it returns a permalink URL built from the base URL and query parameters.
-- **Usage Example:**from modules.storage import generate_permalink
-
-valid_files = [
-    "models/3d_model.glb",
-    "images/model_texture.png",
-    "images/model_depth.png"
-]
-base_url_external = "https://huggingface.co/datasets/Surn/Storage/resolve/main/saved_models/my_model"
-permalink = generate_permalink(valid_files, base_url_external)
-if permalink:
-    print("Permalink:", permalink)
-### 2. `generate_permalink_from_urls(model_url, hm_url, img_url, permalink_viewer_url="surn-3d-viewer.hf.space")`
-- **Purpose:**  
-  Constructs a permalink URL by combining individual URLs for a 3D model (`model_url`), height map (`hm_url`), and image (`img_url`) into a single URL with corresponding query parameters.
-- **Usage Example:**from modules.storage import generate_permalink_from_urls
-
-model_url = "https://example.com/model.glb"
-hm_url = "https://example.com/heightmap.png"
-img_url = "https://example.com/source.png"
-
-permalink = generate_permalink_from_urls(model_url, hm_url, img_url)
-print("Generated Permalink:", permalink)
-### 3. `upload_files_to_repo(files, repo_id, folder_name, create_permalink=False, repo_type="dataset", permalink_viewer_url="surn-3d-viewer.hf.space")`
-- **Purpose:**  
-  Uploads a batch of files (each file represented as a path string) to a specified Hugging Face repository (e.g. `"Surn/Storage"`) under a given folder.
-  The function's return type is `Union[Dict[str, Any], List[Tuple[Any, str]]]`.
-  - When `create_permalink` is `True` and exactly three valid files (one model and two images) are provided, the function returns a dictionary:{
-    "response": <upload_folder_response>,
-    "permalink": "<full_permalink_url>",
-    "short_permalink": "<shortened_permalink_url_with_sid>"
-}  - Otherwise (or if `create_permalink` is `False` or conditions for permalink creation are not met), it returns a list of tuples, where each tuple is `(upload_folder_response, individual_file_link)`.
-  - If no valid files are provided, it returns an empty list `[]` (this case should ideally also return the dictionary with empty/None values for consistency, but currently returns `[]` as per the code).
-- **Usage Example:**
-
-  **a. Uploading with permalink creation:**from modules.storage import upload_files_to_repo
-
-files_for_permalink = [
-    "local/path/to/model.glb",
-    "local/path/to/heightmap.png",
-    "local/path/to/image.png"
-]
-repo_id = "Surn/Storage" # Make sure this is defined, e.g., from constants or environment variables
-folder_name = "my_new_model_with_permalink"
-
-upload_result = upload_files_to_repo(
-    files_for_permalink, 
-    repo_id, 
-    folder_name, 
-    create_permalink=True
-)
-
-if isinstance(upload_result, dict):
-    print("Upload Response:", upload_result.get("response"))
-    print("Full Permalink:", upload_result.get("permalink"))
-    print("Short Permalink:", upload_result.get("short_permalink"))
-elif upload_result: # Check if list is not empty
-    print("Upload Response for individual files:")
-    for res, link in upload_result:
-        print(f"  Response: {res}, Link: {link}")
-else:
-    print("No files uploaded or error occurred.")
-  **b. Uploading without permalink creation (or if conditions for permalink are not met):**from modules.storage import upload_files_to_repo
-
-files_individual = [
-    "local/path/to/another_model.obj",
-    "local/path/to/texture.jpg"
-]
-repo_id = "Surn/Storage"
-folder_name = "my_other_uploads"
-
-upload_results_list = upload_files_to_repo(
-    files_individual, 
-    repo_id, 
-    folder_name, 
-    create_permalink=False # Or if create_permalink=True but not 1 model & 2 images
-)
-
-if upload_results_list: # Will be a list of tuples
-    print("Upload results for individual files:")
-    for res, link in upload_results_list:
-        print(f"  Upload Response: {res}, File Link: {link}")
-else:
-    print("No files uploaded or error occurred.")
-### 4. URL Shortening Functions: `gen_full_url(...)` and Helpers
-The module also enables URL shortening by managing a JSON file (e.g. `shortener.json`) in a Hugging Face repository. It supports CRUD-like operations:
-- **Read:** Look up the full URL using a provided short URL ID.
-- **Create:** Generate a new short URL ID for a full URL if no existing mapping exists.
-- **Update/Conflict Handling:**  
-If both short URL ID and full URL are provided, it checks consistency and either confirms or reports a conflict.
-
-#### `gen_full_url(short_url=None, full_url=None, repo_id=None, repo_type="dataset", permalink_viewer_url="surn-3d-viewer.hf.space", json_file="shortener.json")`
-- **Purpose:**  
-  Based on which parameter is provided, it retrieves or creates a mapping between a short URL ID and a full URL.  
-  - If only `short_url` (the ID) is given, it returns the corresponding `full_url`.  
-  - If only `full_url` is given, it looks up an existing `short_url` ID or generates and stores a new one.  
-  - If both are given, it validates and returns the mapping or an error status.
-- **Returns:** A tuple `(status_message, result_url)`, where `status_message` indicates the outcome (e.g., `"success_retrieved_full"`, `"created_short"`) and `result_url` is the relevant URL (full or short ID).
-- **Usage Examples:**
-
-  **a. Convert a full URL into a short URL ID:**from modules.storage import gen_full_url
-from modules.constants import HF_REPO_ID, SHORTENER_JSON_FILE # Assuming these are defined
-
-full_permalink = "https://surn-3d-viewer.hf.space/?3d=https%3A%2F%2Fexample.com%2Fmodel.glb&hm=https%3A%2F%2Fexample.com%2Fheightmap.png&image=https%3A%2F%2Fexample.com%2Fsource.png"
-
-status, short_id = gen_full_url(
-    full_url=full_permalink, 
-    repo_id=HF_REPO_ID, 
-    json_file=SHORTENER_JSON_FILE
-)
-print("Status:", status)
-if status == "created_short" or status == "success_retrieved_short":
-    print("Shortened URL ID:", short_id)
-    # Construct the full short URL for sharing:
-    # permalink_viewer_url = "surn-3d-viewer.hf.space" # Or from constants
-    # shareable_short_url = f"https://{permalink_viewer_url}/?sid={short_id}"
-    # print("Shareable Short URL:", shareable_short_url)
-  **b. Retrieve the full URL from a short URL ID:**from modules.storage import gen_full_url
-from modules.constants import HF_REPO_ID, SHORTENER_JSON_FILE # Assuming these are defined
-
-short_id_to_lookup = "aBcDeFg1"  # Example short URL ID
-
-status, retrieved_full_url = gen_full_url(
-    short_url=short_id_to_lookup, 
-    repo_id=HF_REPO_ID, 
-    json_file=SHORTENER_JSON_FILE
-)
-print("Status:", status)
-if status == "success_retrieved_full":
-    print("Retrieved Full URL:", retrieved_full_url)
-## 📁 Repository Folder Listing Functions
-
-### 5. `_list_repo_folders(repo_id, path_prefix, repo_type="dataset")`
-- **Purpose:**  
-  List folder names under a given path in a HuggingFace repository. Enables folder-based discovery without index files.
-- **Parameters:**
-  - `repo_id` (str): The repository ID on Hugging Face
-  - `path_prefix` (str): The path prefix to list folders under
-  - `repo_type` (str): Repository type. Default is `"dataset"`.
-- **Returns:** `List[str]` - List of folder names found under the path_prefix.
-- **Usage Example:**
-```python
-from modules.storage import _list_repo_folders
-
-# List all date folders in daily leaderboards
-folders = _list_repo_folders("Surn/Wrdler-Data", "games/leaderboards/daily")
-print("Available dates:", folders)
-# Output: ['2025-01-27', '2025-01-26', '2025-01-25']
-```
-
-### 6. `_list_repo_files_in_folder(repo_id, folder_path, repo_type="dataset")`
-- **Purpose:**  
-  List file names directly under a folder in a HuggingFace repository.
-- **Parameters:**
-  - `repo_id` (str): The repository ID on Hugging Face
-  - `folder_path` (str): The folder path to list files under
-  - `repo_type` (str): Repository type. Default is `"dataset"`.
-- **Returns:** `List[str]` - List of file names found directly in the folder.
-- **Usage Example:**
-```python
-from modules.storage import _list_repo_files_in_folder
-
-files = _list_repo_files_in_folder(
-    "Surn/Wrdler-Data",
-    "games/leaderboards/daily/2025-01-27/classic-classic-0"
-)
-print("Files:", files)
-# Output: ['settings.json']
-```
-
-## 🔑 Cryptographic Key Management Functions
-
-### 7. `store_issuer_keypair(issuer_id, public_key, private_key, repo_id=None)`
-- **Purpose:**  
-  Securely store cryptographic keys for an issuer in a private Hugging Face repository. Private keys are encrypted before storage.
-- **⚠️ IMPORTANT:** This function requires a PRIVATE Hugging Face repository to ensure the security of stored private keys. Never use this with public repositories.
-- **Storage Structure:**keys/issuers/{issuer_id}/
-├── private_key.json (encrypted)
-└── public_key.json- **Returns:** `bool` - True if keys were stored successfully, False otherwise.
-- **Usage Example:**from modules.storage import store_issuer_keypair
-
-# Example Ed25519 keys (multibase encoded)
-issuer_id = "https://example.edu/issuers/565049"
-public_key = "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
-private_key = "z3u2MQhLnQw7nvJRGJCdKdqfXHV4N7BLKuEGFWnJqsVSdgYv"
-
-success = store_issuer_keypair(issuer_id, public_key, private_key)
-if success:
-    print("Keys stored successfully")
-else:
-    print("Failed to store keys")
-### 8. `get_issuer_keypair(issuer_id, repo_id=None)`
-- **Purpose:**  
-  Retrieve and decrypt stored cryptographic keys for an issuer from the private Hugging Face repository.
-- **⚠️ IMPORTANT:** This function accesses a PRIVATE Hugging Face repository containing encrypted private keys. Ensure proper access control and security measures.
-- **Returns:** `Tuple[Optional[str], Optional[str]]` - (public_key, private_key) or (None, None) if not found.
-- **Usage Example:**from modules.storage import get_issuer_keypair
-
-issuer_id = "https://example.edu/issuers/565049"
-public_key, private_key = get_issuer_keypair(issuer_id)
-
-if public_key and private_key:
-    print("Keys retrieved successfully")
-    print(f"Public key: {public_key}")
-    # Use private_key for signing operations
-else:
-    print("Keys not found or error occurred")
-### 9. `get_verification_methods_registry(repo_id=None)`
-- **Purpose:**  
-  Retrieve the global verification methods registry containing all registered issuer public keys.
-- **Returns:** `Dict[str, Any]` - Registry data containing all verification methods.
-- **Usage Example:**from modules.storage import get_verification_methods_registry
-
-registry = get_verification_methods_registry()
-methods = registry.get("verification_methods", [])
-
-for method in methods:
-    print(f"Issuer: {method['issuer_id']}")
-    print(f"Public Key: {method['public_key']}")
-    print(f"Key Type: {method['key_type']}")
-    print("---")
-### 10. `list_issuer_ids(repo_id=None)`
-- **Purpose:**  
-  List all issuer IDs that have stored keys in the repository.
-- **Returns:** `List[str]` - List of issuer IDs.
-- **Usage Example:**from modules.storage import list_issuer_ids
-
-issuer_ids = list_issuer_ids()
-print("Registered issuers:")
-for issuer_id in issuer_ids:
-    print(f"  - {issuer_id}")
-## Notes
-- **Authentication:** All functions that interact with Hugging Face Hub use the HF API token defined as `HF_API_TOKEN` in `modules/constants.py`. Ensure this environment variable is correctly set.
-- **Constants:** Functions like `gen_full_url` and `upload_files_to_repo` (when creating short links) rely on `HF_REPO_ID` and `SHORTENER_JSON_FILE` from `modules/constants.py` for the URL shortening feature.
-- **🔐 Private Repository Requirement:** Key management functions require a PRIVATE Hugging Face repository to ensure the security of stored encrypted private keys. Never use these functions with public repositories.
-- **File Types:** Only files with extensions included in `upload_file_types` (a combination of `model_extensions` and `image_extensions` from `modules/constants.py`) are processed by `upload_files_to_repo`.
-- **Repository Configuration:** When using URL shortening, file uploads, and key management, ensure that the specified Hugging Face repository (e.g., defined by `HF_REPO_ID`) exists and that you have write permissions.
-- **Temporary Directory:** `upload_files_to_repo` temporarily copies files to a local directory (configured by `TMPDIR` in `modules/constants.py`) before uploading.
-- **Key Encryption:** Private keys are encrypted using basic XOR encryption (demo implementation). In production environments, upgrade to proper encryption like Fernet from the cryptography library.
-- **Error Handling:** Functions include basic error handling (e.g., catching `RepositoryNotFoundError`, `EntryNotFoundError`, JSON decoding errors, or upload issues) and print messages to the console for debugging. Review function return values to handle these cases appropriately in your application.
-
-## 🔒 Security Considerations for Key Management
-
-1. **Private Repository Only:** Always use private repositories for key storage to protect cryptographic material.
-2. **Key Sanitization:** Issuer IDs are sanitized for file system compatibility (replacing special characters with underscores).
-3. **Encryption:** Private keys are encrypted before storage. Upgrade to Fernet encryption in production.
-4. **Access Control:** Implement proper authentication and authorization for key access.
-5. **Key Rotation:** Consider implementing key rotation mechanisms for enhanced security.
-6. **Audit Logging:** Monitor key access and usage patterns for security auditing.
-
----
-
-This guide provides the essential usage examples for interacting with the storage, URL-shortening, folder listing, and cryptographic key management functionality. You can integrate these examples into your application or use them as a reference when extending functionality.

battlewords/modules/storage.py

@@ -1,799 +0,0 @@
-# modules/storage.py
-__version__ = "0.1.6"
-import os
-import urllib.parse
-import tempfile
-import shutil
-import json
-import base64
-import logging
-from datetime import datetime, timezone
-from huggingface_hub import login, upload_folder, hf_hub_download, HfApi
-from huggingface_hub.utils import RepositoryNotFoundError, EntryNotFoundError
-from .constants import HF_API_TOKEN, upload_file_types, model_extensions, image_extensions, audio_extensions, video_extensions, doc_extensions, HF_REPO_ID, SHORTENER_JSON_FILE
-from typing import Any, Dict, List, Tuple, Union, Optional
-
-# Configure professional logging
-logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
-logger = logging.getLogger(__name__)
-
-# see storage.md for detailed information about the storage module and its functions.
-
-def generate_permalink(valid_files, base_url_external, permalink_viewer_url="surn-3d-viewer.hf.space"):
-    """
-    Given a list of valid files, checks if they contain exactly 1 model file and 2 image files.
-    Constructs and returns a permalink URL with query parameters if the criteria is met.
-    Otherwise, returns None.
-    """
-    model_link = None
-    images_links = []
-    audio_links = []
-    video_links = []
-    doc_links = []
-    for f in valid_files:
-        filename = os.path.basename(f)
-        ext = os.path.splitext(filename)[1].lower()
-        if ext in model_extensions:
-            if model_link is None:
-                model_link = f"{base_url_external}/{filename}"
-        elif ext in image_extensions:
-            images_links.append(f"{base_url_external}/{filename}")
-        elif ext in audio_extensions:
-            audio_links.append(f"{base_url_external}/{filename}")
-        elif ext in video_extensions:
-            video_links.append(f"{base_url_external}/{filename}")
-        elif ext in doc_extensions:
-            doc_links.append(f"{base_url_external}/{filename}")
-    if model_link and len(images_links) == 2:
-        # Construct a permalink to the viewer project with query parameters.
-        permalink_viewer_url = f"https://{permalink_viewer_url}/"
-        params = {"3d": model_link, "hm": images_links[0], "image": images_links[1]}
-        query_str = urllib.parse.urlencode(params)
-        return f"{permalink_viewer_url}?{query_str}"
-    return None
-
-def generate_permalink_from_urls(model_url, hm_url, img_url, permalink_viewer_url="surn-3d-viewer.hf.space"):
-    """
-    Constructs and returns a permalink URL with query string parameters for the viewer.
-    Each parameter is passed separately so that the image positions remain consistent.
-    
-    Parameters:
-        model_url (str): Processed URL for the 3D model.
-        hm_url (str): Processed URL for the height map image.
-        img_url (str): Processed URL for the main image.
-        permalink_viewer_url (str): The base viewer URL.
-    
-    Returns:
-        str: The generated permalink URL.
-    """
-    import urllib.parse
-    params = {"3d": model_url, "hm": hm_url, "image": img_url}
-    query_str = urllib.parse.urlencode(params)
-    return f"https://{permalink_viewer_url}/?{query_str}"
-
-def upload_files_to_repo(
-    files: List[Any],
-    repo_id: str,
-    folder_name: str,
-    create_permalink: bool = False,
-    repo_type: str = "dataset",
-    permalink_viewer_url: str = "surn-3d-viewer.hf.space"
-) -> Union[Dict[str, Any], List[Tuple[Any, str]]]:
-    """
-    Uploads multiple files to a Hugging Face repository using a batch upload approach via upload_folder.
-
-    Parameters:
-        files (list): A list of file paths (str) to upload.
-        repo_id (str): The repository ID on Hugging Face for storage, e.g. "Surn/Storage".
-        folder_name (str): The subfolder within the repository where files will be saved.
-        create_permalink (bool): If True and if exactly three files are uploaded (1 model and 2 images),
-                                 returns a single permalink to the project with query parameters.
-                                 Otherwise, returns individual permalinks for each file.
-        repo_type (str): Repository type ("space", "dataset", etc.). Default is "dataset".
-        permalink_viewer_url (str): The base viewer URL.
-
-    Returns:
-        Union[Dict[str, Any], List[Tuple[Any, str]]]:
-            If create_permalink is True and files match the criteria:
-                dict: {
-                    "response": <upload response>,
-                    "permalink": <full_permalink URL>,
-                    "short_permalink": <shortened permalink URL>
-                }
-            Otherwise:
-                list: A list of tuples (response, permalink) for each file.
-    """
-    logger.info(f"📤 Starting batch upload to repository: {repo_id}")
-    logger.debug(f"📁 Target folder: {folder_name}")
-    logger.debug(f"🔗 Create permalink: {create_permalink}")
-    
-    # Log in using the HF API token.
-    try:
-        login(token=HF_API_TOKEN)
-        logger.debug("🔑 Authenticated with Hugging Face")
-    except Exception as e:
-        logger.error(f"🚫 Authentication failed: {e}")
-        return {"response": "Authentication failed", "permalink": None, "short_permalink": None} if create_permalink else []
-    
-    valid_files = []
-    permalink_short = None
-    
-    # Ensure folder_name does not have a trailing slash.
-    folder_name = folder_name.rstrip("/")
-    
-    # Filter for valid files based on allowed extensions.
-    logger.debug("🔍 Filtering valid files...")
-    for f in files:
-        file_name = f if isinstance(f, str) else f.name if hasattr(f, "name") else None
-        if file_name is None:
-            continue
-        ext = os.path.splitext(file_name)[1].lower()
-        if ext in upload_file_types:
-            valid_files.append(f)
-            logger.debug(f"✅ Valid file: {os.path.basename(file_name)}")
-        else:
-            logger.debug(f"⚠️ Skipped file with invalid extension: {os.path.basename(file_name)}")
-    
-    logger.info(f"📊 Found {len(valid_files)} valid files out of {len(files)} total")
-    
-    if not valid_files:
-        logger.warning("⚠️ No valid files to upload")
-        if create_permalink:
-            return {
-                "response": "No valid files to upload.",
-                "permalink": None,
-                "short_permalink": None
-            }
-        return [] 
-    
-    # Create a temporary directory and copy valid files
-    logger.debug("📁 Creating temporary directory for batch upload...")
-    with tempfile.TemporaryDirectory(dir=os.getenv("TMPDIR", "/tmp")) as temp_dir:
-        for file_path in valid_files:
-            filename = os.path.basename(file_path)
-            dest_path = os.path.join(temp_dir, filename)
-            shutil.copy(file_path, dest_path)
-            logger.debug(f"📄 Copied: {filename}")
-        
-        logger.info("🚀 Starting batch upload to Hugging Face...")
-        # Batch upload all files in the temporary folder.
-        try:
-            response = upload_folder(
-                folder_path=temp_dir,
-                repo_id=repo_id,
-                repo_type=repo_type,
-                path_in_repo=folder_name,
-                commit_message="Batch upload files"
-            )
-            logger.info("✅ Batch upload completed successfully")
-        except Exception as e:
-            logger.error(f"❌ Batch upload failed: {e}")
-            return {"response": f"Upload failed: {e}", "permalink": None, "short_permalink": None} if create_permalink else []
-    
-    # Construct external URLs for each uploaded file.
-    base_url_external = f"https://huggingface.co/datasets/{repo_id}/resolve/main/{folder_name}"
-    individual_links = []
-    for file_path in valid_files:
-        filename = os.path.basename(file_path)
-        link = f"{base_url_external}/{filename}"
-        individual_links.append(link)
-        logger.debug(f"🔗 Generated link: {link}")
-    
-    # Handle permalink creation if requested
-    if create_permalink:
-        logger.info("🔗 Attempting to create permalink...")
-        permalink = generate_permalink(valid_files, base_url_external, permalink_viewer_url)
-        if permalink:
-            logger.info(f"✅ Generated permalink: {permalink}")
-            logger.debug("🔗 Creating short URL...")
-            status, short_id = gen_full_url(
-                full_url=permalink,
-                repo_id=HF_REPO_ID,
-                json_file=SHORTENER_JSON_FILE
-            )
-            if status in ["created_short", "success_retrieved_short", "exists_match"]:
-                permalink_short = f"https://{permalink_viewer_url}/?sid={short_id}"
-                logger.info(f"✅ Created short permalink: {permalink_short}")
-            else:
-                permalink_short = None 
-                logger.warning(f"⚠️ URL shortening failed: {status} for {permalink}")
-
-            return {
-                "response": response,
-                "permalink": permalink,
-                "short_permalink": permalink_short
-            }
-        else:
-            logger.warning("⚠️ Permalink generation failed (criteria not met)")
-            return {
-                "response": response,
-                "permalink": None,
-                "short_permalink": None
-            }
-
-    # Return individual tuples for each file
-    logger.info(f"📋 Returning individual links for {len(individual_links)} files")
-    return [(response, link) for link in individual_links]
-
-def _generate_short_id(length=8):
-    """Generates a random base64 URL-safe string."""
-    return base64.urlsafe_b64encode(os.urandom(length * 2))[:length].decode('utf-8')
-
-def _get_json_from_repo(repo_id, json_file_name, repo_type="dataset"):
-    """Downloads and loads the JSON file from the repo. Returns empty list if not found or error."""
-    try:
-        login(token=HF_API_TOKEN)
-        json_path = hf_hub_download(
-            repo_id=repo_id,
-            filename=json_file_name,
-            repo_type=repo_type,
-            token=HF_API_TOKEN
-        )
-        with open(json_path, 'r') as f:
-            data = json.load(f)
-        os.remove(json_path)
-        return data
-    except RepositoryNotFoundError:
-        logger.warning(f"Repository {repo_id} not found.")
-        return []
-    except EntryNotFoundError:
-        logger.warning(f"JSON file {json_file_name} not found in {repo_id}. Initializing with empty list.")
-        return []
-    except json.JSONDecodeError:
-        logger.error(f"Error decoding JSON from {json_file_name}. Returning empty list.")
-        return []
-    except Exception as e:
-        logger.error(f"An unexpected error occurred while fetching {json_file_name}: {e}")
-        return []
-
-def _get_files_from_repo(repo_id, file_name, repo_type="dataset"):
-    """Downloads and loads the file from the repo. File must be in upload_file_types. Returns empty list if not found or error."""
-    filename = os.path.basename(file_name)
-    ext = os.path.splitext(file_name)[1].lower() 
-    if ext not in upload_file_types:
-        logger.error(f"File {filename} with extension {ext} is not allowed for upload.")
-        return None
-    else:
-        try:
-            login(token=HF_API_TOKEN)
-            file_path = hf_hub_download(
-                repo_id=repo_id,
-                filename=file_name,
-                repo_type=repo_type,
-                token=HF_API_TOKEN
-            )
-            if not file_path:
-                return None
-            return file_path
-        except RepositoryNotFoundError:
-            logger.warning(f"Repository {repo_id} not found.")
-            return None
-        except EntryNotFoundError:
-            logger.warning(f"file {file_name} not found in {repo_id}. Initializing with empty list.")
-            return None
-        except Exception as e:
-            logger.error(f"Error fetching {file_name} from {repo_id}: {e}")
-            return None
-
-def _upload_json_to_repo(data, repo_id, json_file_name, repo_type="dataset"):
-    """Uploads the JSON data to the specified file in the repo."""
-    try:
-        login(token=HF_API_TOKEN)
-        api = HfApi()
-        # Use a temporary directory specified by TMPDIR or default to system temp
-        temp_dir_for_json = os.getenv("TMPDIR", tempfile.gettempdir())
-        os.makedirs(temp_dir_for_json, exist_ok=True)
-
-        with tempfile.NamedTemporaryFile(mode="w+", delete=False, suffix=".json", dir=temp_dir_for_json) as tmp_file:
-            json.dump(data, tmp_file, indent=2)
-            tmp_file_path = tmp_file.name
-        
-        logger.info(f"📤 Uploading JSON data to {json_file_name}...")
-        api.upload_file(
-            path_or_fileobj=tmp_file_path,
-            path_in_repo=json_file_name,
-            repo_id=repo_id,
-            repo_type=repo_type,
-            commit_message=f"Update {json_file_name}"
-        )
-        os.remove(tmp_file_path) # Clean up temporary file
-        logger.info("✅ JSON data uploaded successfully")
-        return True
-    except Exception as e:
-        logger.error(f"Failed to upload {json_file_name} to {repo_id}: {e}")
-        if 'tmp_file_path' in locals() and os.path.exists(tmp_file_path):
-            os.remove(tmp_file_path) # Ensure cleanup on error too
-        return False
-
-def _find_url_in_json(data, short_url=None, full_url=None):
-    """
-    Searches the JSON data.
-    If short_url is provided, returns the corresponding full_url or None.
-    If full_url is provided, returns the corresponding short_url or None.
-    """
-    if not data: # Handles cases where data might be None or empty
-        return None
-    if short_url:
-        for item in data:
-            if item.get("short_url") == short_url:
-                return item.get("full_url")
-    if full_url:
-        for item in data:
-            if item.get("full_url") == full_url:
-                return item.get("short_url")
-    return None
-
-def _add_url_to_json(data, short_url, full_url):
-    """Adds a new short_url/full_url pair to the data. Returns updated data."""
-    if data is None: 
-        data = []
-    data.append({"short_url": short_url, "full_url": full_url})
-    return data
-
-def gen_full_url(short_url=None, full_url=None, repo_id=None, repo_type="dataset", permalink_viewer_url="surn-3d-viewer.hf.space", json_file="shortener.json"):
-    """
-    Manages short URLs and their corresponding full URLs in a JSON file stored in a Hugging Face repository.
-
-    - If short_url is provided, attempts to retrieve and return the full_url.
-    - If full_url is provided, attempts to retrieve an existing short_url or creates a new one, stores it, and returns the short_url.
-    - If both are provided, checks for consistency or creates a new entry.
-    - If neither is provided, or repo_id is missing, returns an error status.
-
-    Returns:
-        tuple: (status_message, result_url)
-               status_message can be "success", "created", "exists", "error", "not_found".
-               result_url is the relevant URL (short or full) or None if an error occurs or not found.
-    """
-    if not repo_id:
-        return "error_repo_id_missing", None
-    if not short_url and not full_url:
-        return "error_no_input", None
-
-    login(token=HF_API_TOKEN) # Ensure login at the beginning
-    url_data = _get_json_from_repo(repo_id, json_file, repo_type)
-
-    # Case 1: Only short_url provided (lookup full_url)
-    if short_url and not full_url:
-        found_full_url = _find_url_in_json(url_data, short_url=short_url)
-        return ("success_retrieved_full", found_full_url) if found_full_url else ("not_found_short", None)
-
-    # Case 2: Only full_url provided (lookup or create short_url)
-    if full_url and not short_url:
-        existing_short_url = _find_url_in_json(url_data, full_url=full_url)
-        if existing_short_url:
-            return "success_retrieved_short", existing_short_url
-        else:
-            # Create new short_url
-            new_short_id = _generate_short_id()
-            url_data = _add_url_to_json(url_data, new_short_id, full_url)
-            if _upload_json_to_repo(url_data, repo_id, json_file, repo_type):
-                return "created_short", new_short_id 
-            else:
-                return "error_upload", None
-
-    # Case 3: Both short_url and full_url provided
-    if short_url and full_url:
-        found_full_for_short = _find_url_in_json(url_data, short_url=short_url)
-        found_short_for_full = _find_url_in_json(url_data, full_url=full_url)
-
-        if found_full_for_short == full_url: 
-            return "exists_match", short_url 
-        if found_full_for_short is not None and found_full_for_short != full_url: 
-            return "error_conflict_short_exists_different_full", short_url
-        if found_short_for_full is not None and found_short_for_full != short_url:
-            return "error_conflict_full_exists_different_short", found_short_for_full
-        
-        # If short_url is provided and not found, or full_url is provided and not found,
-        # or neither is found, then create a new entry with the provided short_url and full_url.
-        # This effectively allows specifying a custom short_url if it's not already taken.
-        url_data = _add_url_to_json(url_data, short_url, full_url)
-        if _upload_json_to_repo(url_data, repo_id, json_file, repo_type):
-            return "created_specific_pair", short_url
-        else:
-            return "error_upload", None
-                 
-    return "error_unhandled_case", None # Should not be reached
-
-def _encrypt_private_key(private_key: str, password: str = None) -> str:
-    """
-    Basic encryption for private keys. In production, use proper encryption like Fernet.
-    
-    Note: This is a simplified encryption for demonstration. In production environments,
-    use proper encryption libraries like cryptography.fernet.Fernet with secure key derivation.
-    
-    Args:
-        private_key (str): The private key to encrypt
-        password (str, optional): Password for encryption. If None, uses a default method.
-    
-    Returns:
-        str: Base64 encoded encrypted private key
-    """
-    # WARNING: This is a basic XOR encryption for demo purposes only
-    # In production, use proper encryption like Fernet from cryptography library
-    if not password:
-        password = "default_encryption_key"  # In production, use secure key derivation
-    
-    encrypted_bytes = []
-    for i, char in enumerate(private_key):
-        encrypted_bytes.append(ord(char) ^ ord(password[i % len(password)]))
-    
-    encrypted_data = bytes(encrypted_bytes)
-    return base64.b64encode(encrypted_data).decode('utf-8')
-
-def _decrypt_private_key(encrypted_private_key: str, password: str = None) -> str:
-    """
-    Basic decryption for private keys. In production, use proper decryption like Fernet.
-    
-    Args:
-        encrypted_private_key (str): Base64 encoded encrypted private key
-        password (str, optional): Password for decryption. If None, uses a default method.
-    
-    Returns:
-        str: Decrypted private key
-    """
-    # WARNING: This is a basic XOR decryption for demo purposes only
-    if not password:
-        password = "default_encryption_key"  # In production, use secure key derivation
-    
-    encrypted_data = base64.b64decode(encrypted_private_key)
-    decrypted_chars = []
-    for i, byte in enumerate(encrypted_data):
-        decrypted_chars.append(chr(byte ^ ord(password[i % len(password)])))
-    
-    return ''.join(decrypted_chars)
-
-def store_issuer_keypair(issuer_id: str, public_key: str, private_key: str, repo_id: str = None) -> bool:
-    """
-    Store cryptographic keys for an issuer in the private Hugging Face repository.
-    
-    **IMPORTANT: This function requires a PRIVATE Hugging Face repository to ensure
-    the security of stored private keys. Never use this with public repositories.**
-    
-    The keys are stored in the following structure:
-    keys/issuers/{issuer_id}/
-    ├── private_key.json (encrypted)
-    └── public_key.json
-    
-    Args:
-        issuer_id (str): Unique identifier for the issuer (e.g., "https://example.edu/issuers/565049")
-        public_key (str): Multibase-encoded public key
-        private_key (str): Multibase-encoded private key (will be encrypted before storage)
-        repo_id (str, optional): Repository ID. If None, uses HF_REPO_ID from constants.
-    
-    Returns:
-        bool: True if keys were stored successfully, False otherwise
-    
-    Raises:
-        ValueError: If issuer_id, public_key, or private_key are empty
-        Exception: If repository operations fail
-    
-    Example:
-        >>> public_key = "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
-        >>> private_key = "z3u2MQhLnQw7nvJRGJCdKdqfXHV4N7BLKuEGFWnJqsVSdgYv"
-        >>> success = store_issuer_keypair("https://example.edu/issuers/565049", public_key, private_key)
-        >>> print(f"Keys stored: {success}")
-    """
-    if not issuer_id or not public_key or not private_key:
-        logger.error("❌ Missing required parameters: issuer_id, public_key, and private_key are required")
-        raise ValueError("issuer_id, public_key, and private_key are required")
-    
-    if not repo_id:
-        repo_id = HF_REPO_ID
-        logger.debug(f"🔧 Using default repository: {repo_id}")
-    
-    # Sanitize issuer_id for use as folder name
-    safe_issuer_id = issuer_id.replace("https://", "").replace("http://", "").replace("/", "_").replace(":", "_")
-    logger.info(f"🔑 Storing keypair for issuer: {issuer_id}")
-    logger.debug(f"🗂️ Safe issuer ID: {safe_issuer_id}")
-    
-    try:
-        # Encrypt the private key before storage
-        encrypted_private_key = _encrypt_private_key(private_key)
-        logger.debug("🔐 Private key encrypted successfully")
-        
-        # Prepare key data structures
-        private_key_data = {
-            "issuer_id": issuer_id,
-            "encrypted_private_key": encrypted_private_key,
-            "key_type": "Ed25519VerificationKey2020",
-            "created_at": datetime.now(timezone.utc).isoformat(),
-            "encryption_method": "basic_xor"  # In production, use proper encryption
-        }
-        
-        public_key_data = {
-            "issuer_id": issuer_id,
-            "public_key": public_key,
-            "key_type": "Ed25519VerificationKey2020",
-            "created_at": datetime.now(timezone.utc).isoformat()
-        }
-        
-        logger.info("📤 Uploading private key...")
-        # Store private key
-        private_key_path = f"keys/issuers/{safe_issuer_id}/private_key.json"
-        private_key_success = _upload_json_to_repo(private_key_data, repo_id, private_key_path, "dataset")
-        
-        logger.info("📤 Uploading public key...")
-        # Store public key
-        public_key_path = f"keys/issuers/{safe_issuer_id}/public_key.json"
-        public_key_success = _upload_json_to_repo(public_key_data, repo_id, public_key_path, "dataset")
-        
-        # Update global verification methods registry
-        if private_key_success and public_key_success:
-            logger.info("📋 Updating verification methods registry...")
-            _update_verification_methods_registry(issuer_id, safe_issuer_id, public_key, repo_id)
-            logger.info("✅ Keypair stored successfully and registry updated")
-        else:
-            logger.error("❌ Failed to store one or both keys")
-        
-        return private_key_success and public_key_success
-        
-    except Exception as e:
-        logger.error(f"💥 Error storing issuer keypair for {issuer_id}: {e}")
-        return False
-
-def get_issuer_keypair(issuer_id: str, repo_id: str = None) -> Tuple[Optional[str], Optional[str]]:
-    """
-    Retrieve stored cryptographic keys for an issuer from the private Hugging Face repository.
-    
-    **IMPORTANT: This function accesses a PRIVATE Hugging Face repository containing
-    encrypted private keys. Ensure proper access control and security measures.**
-
-        Args:
-        issuer_id (str): Unique identifier for the issuer
-        repo_id (str, optional): Repository ID. If None, uses HF_REPO_ID from constants.
-    
-    Returns:
-        Tuple[Optional[str], Optional[str]]: (public_key, private_key) or (None, None) if not found
-        
-    Raises:
-        ValueError: If issuer_id is empty
-        Exception: If repository operations fail or decryption fails
-    
-    Example:
-        >>> public_key, private_key = get_issuer_keypair("https://example.edu/issuers/565049")
-        >>> if public_key and private_key:
-        ...     print("Keys retrieved successfully")
-        ... else:
-        ...     print("Keys not found")
-    """
-    if not issuer_id:
-        logger.error("❌ issuer_id is required")
-        raise ValueError("issuer_id is required")
-    
-    if not repo_id:
-        repo_id = HF_REPO_ID
-        logger.debug(f"🔧 Using default repository: {repo_id}")
-    
-    # Sanitize issuer_id for use as folder name
-    safe_issuer_id = issuer_id.replace("https://", "").replace("http://", "").replace("/", "_").replace(":", "_")
-    logger.info(f"🔍 Retrieving keypair for issuer: {issuer_id}")
-    logger.debug(f"🗂️ Safe issuer ID: {safe_issuer_id}")
-    
-    try:
-        logger.debug("📥 Retrieving public key...")
-        # Retrieve public key
-        public_key_path = f"keys/issuers/{safe_issuer_id}/public_key.json"
-        public_key_data = _get_json_from_repo(repo_id, public_key_path, "dataset")
-        
-        logger.debug("📥 Retrieving private key...")
-        # Retrieve private key
-        private_key_path = f"keys/issuers/{safe_issuer_id}/private_key.json"
-        private_key_data = _get_json_from_repo(repo_id, private_key_path, "dataset")
-        
-        if not public_key_data or not private_key_data:
-            logger.warning(f"⚠️ Keys not found for issuer {issuer_id}")
-            return None, None
-        
-        # Extract and decrypt private key
-        encrypted_private_key = private_key_data.get("encrypted_private_key")
-        if not encrypted_private_key:
-            logger.error(f"❌ No encrypted private key found for issuer {issuer_id}")
-            return None, None
-        
-        logger.debug("🔓 Decrypting private key...")
-        decrypted_private_key = _decrypt_private_key(encrypted_private_key)
-        public_key = public_key_data.get("public_key")
-        
-        logger.info(f"✅ Successfully retrieved keypair for issuer {issuer_id}")
-        return public_key, decrypted_private_key
-        
-    except Exception as e:
-        logger.error(f"💥 Error retrieving issuer keypair for {issuer_id}: {e}")
-        return None, None
-
-def _update_verification_methods_registry(issuer_id: str, safe_issuer_id: str, public_key: str, repo_id: str):
-    """
-    Update the global verification methods registry with new issuer public key.
-    
-    Args:
-        issuer_id (str): Original issuer ID
-        safe_issuer_id (str): Sanitized issuer ID for file system
-        public_key (str): Public key to register
-        repo_id (str): Repository ID
-    """
-    try:
-        registry_path = "keys/global/verification_methods.json"
-        registry_data = _get_json_from_repo(repo_id, registry_path, "dataset")
-        
-        if not registry_data:
-            registry_data = {"verification_methods": []}
-        
-        # Check if issuer already exists in registry
-        existing_entry = None
-        for i, method in enumerate(registry_data.get("verification_methods", [])):
-            if method.get("issuer_id") == issuer_id:
-                existing_entry = i
-                break
-        
-        # Create new verification method entry
-        verification_method = {
-            "issuer_id": issuer_id,
-            "safe_issuer_id": safe_issuer_id,
-            "public_key": public_key,
-            "key_type": "Ed25519VerificationKey2020",
-            "updated_at": datetime.now(timezone.utc).isoformat()
-        }
-        
-        if existing_entry is not None:
-            # Update existing entry
-            registry_data["verification_methods"][existing_entry] = verification_method
-            logger.info(f"♻️ Updated verification method for issuer {issuer_id}")
-        else:
-            # Add new entry
-            registry_data["verification_methods"].append(verification_method)
-            logger.info(f"➕ Added new verification method for issuer {issuer_id}")
-        
-        # Upload updated registry
-        _upload_json_to_repo(registry_data, repo_id, registry_path, "dataset")
-        logger.info("✅ Verification methods registry updated successfully")
-        
-    except Exception as e:
-        logger.error(f"Error updating verification methods registry: {e}")
-
-def get_verification_methods_registry(repo_id: str = None) -> Dict[str, Any]:
-    """
-    Retrieve the global verification methods registry.
-    
-    Args:
-        repo_id (str, optional): Repository ID. If None, uses HF_REPO_ID from constants.
-    
-    Returns:
-        Dict[str, Any]: Registry data containing all verification methods
-    """
-    if not repo_id:
-        repo_id = HF_REPO_ID
-    
-    try:
-        registry_path = "keys/global/verification_methods.json"
-        registry_data = _get_json_from_repo(repo_id, registry_path, "dataset")
-        return registry_data if registry_data else {"verification_methods": []}
-    except Exception as e:
-        logger.error(f"Error retrieving verification methods registry: {e}")
-        return {"verification_methods": []}
-
-def list_issuer_ids(repo_id: str = None) -> List[str]:
-    """
-    List all issuer IDs that have stored keys in the repository.
-    
-    Args:
-        repo_id (str, optional): Repository ID. If None, uses HF_REPO_ID from constants.
-    
-    Returns:
-        List[str]: List of issuer IDs
-    """
-    if not repo_id:
-        repo_id = HF_REPO_ID
-    
-    try:
-        registry = get_verification_methods_registry(repo_id)
-        return [method["issuer_id"] for method in registry.get("verification_methods", [])]
-    except Exception as e:
-        logger.error(f"Error listing issuer IDs: {e}")
-        return []
-
-def _list_repo_folders(repo_id: str, path_prefix: str, repo_type: str = "dataset") -> List[str]:
-    """
-    List folder names under a given path in a HuggingFace repository.
-    
-    Args:
-        repo_id: The repository ID on Hugging Face
-        path_prefix: The path prefix to list folders under (e.g., "leaderboards/daily/2025-01-27")
-        repo_type: Repository type ("dataset", "model", "space"). Default is "dataset".
-    
-    Returns:
-        List of folder names (not full paths) found under the path_prefix.
-        Returns empty list if path not found or on error.
-    """
-    try:
-        login(token=HF_API_TOKEN)
-        api = HfApi()
-        
-        # List all files in the repo under the prefix
-        # The list_repo_files returns file paths, so we extract unique folder names
-        all_files = api.list_repo_files(
-            repo_id=repo_id,
-            repo_type=repo_type,
-            token=HF_API_TOKEN
-        )
-        
-        # Ensure path_prefix ends with /
-        if path_prefix and not path_prefix.endswith("/"):
-            path_prefix = path_prefix + "/"
-        
-        folders = set()
-        for file_path in all_files:
-            if file_path.startswith(path_prefix):
-                # Get the relative path after the prefix
-                relative_path = file_path[len(path_prefix):]
-                # Extract the first folder name (before any /)
-                if "/" in relative_path:
-                    folder_name = relative_path.split("/")[0]
-                    folders.add(folder_name)
-        
-        return sorted(list(folders))
-    
-    except RepositoryNotFoundError:
-        logger.warning(f"Repository {repo_id} not found.")
-        return []
-    except Exception as e:
-        logger.error(f"Error listing folders in {repo_id}/{path_prefix}: {e}")
-        return []
-
-
-def _list_repo_files_in_folder(repo_id: str, folder_path: str, repo_type: str = "dataset") -> List[str]:
-    """
-    List file names (not full paths) directly under a folder in a HuggingFace repository.
-    
-    Args:
-        repo_id: The repository ID on Hugging Face
-        folder_path: The folder path to list files under
-        repo_type: Repository type. Default is "dataset".
-    
-    Returns:
-        List of file names found directly in the folder.
-    """
-    try:
-        login(token=HF_API_TOKEN)
-        api = HfApi()
-        
-        all_files = api.list_repo_files(
-            repo_id=repo_id,
-            repo_type=repo_type,
-            token=HF_API_TOKEN
-        )
-        
-        # Ensure folder_path ends with /
-        if folder_path and not folder_path.endswith("/"):
-            folder_path = folder_path + "/"
-        
-        files = []
-        for file_path in all_files:
-            if file_path.startswith(folder_path):
-                relative_path = file_path[len(folder_path):]
-                # Only include files directly in this folder (no subdirectories)
-                if "/" not in relative_path and relative_path:
-                    files.append(relative_path)
-        
-        return sorted(files)
-    
-    except RepositoryNotFoundError:
-        logger.warning(f"Repository {repo_id} not found.")
-        return []
-    except Exception as e:
-        logger.error(f"Error listing files in {repo_id}/{folder_path}: {e}")
-        return []
-
-if __name__ == "__main__":
-   issuer_id = "https://example.edu/issuers/565049"
-   # Example usage
-   public_key, private_key = get_issuer_keypair(issuer_id)
-   print(f"Public Key: {public_key}")
-   print(f"Private Key: {private_key}")
-
-   # Example to store keys
-   store_issuer_keypair(issuer_id, public_key, private_key)
-
-   # Example to list issuer IDs
-   issuer_ids = list_issuer_ids()
-
-   print(f"Issuer IDs: {issuer_ids}")

battlewords/ui.py

@@ -18,8 +18,8 @@ from .generator import generate_puzzle
 from .logic import build_letter_map, reveal_cell, guess_word, is_game_over, compute_tier, auto_mark_completed_words, hidden_word_display
 from .models import Coord, GameState, Puzzle
 from .word_loader import get_wordlist_files, load_word_list, compute_word_difficulties
-from .game_storage import load_game_from_sid, save_game_to_hf, get_shareable_url, add_user_result_to_game
-from .ui_helpers import inject_styles, fig_to_pil_rgba, ocean_background_css, inject_ocean_layers, pwa_service_worker, show_spinner, fade_out_spinner, start_root_fade_in, finish_root_fade_in
+from .ui_helpers import inject_styles, fig_to_pil_rgba, ocean_background_css, inject_ocean_layers, show_spinner, fade_out_spinner, start_root_fade_in, finish_root_fade_in
+from .modules.version_info import versions_html
 
 # --- Spinner context manager for custom spinner ---
 class CustomSpinner:
@@ -77,10 +77,6 @@ def _init_session() -> None:
     spinner_placeholder = st.empty()
     with CustomSpinner(spinner_placeholder, "Initializing session..."):
         # --- Load most recent settings from settings/settings.json ---
-        # --- Preserve music settings ---
-
-        # Check if we're loading a shared game
-        shared_settings = st.session_state.get("shared_game_settings")
 
         # Ensure a default selection exists before creating the puzzle
         files = get_wordlist_files()
@@ -89,34 +85,9 @@ def _init_session() -> None:
         if "game_mode" not in st.session_state:
             st.session_state.game_mode = "classic"
 
-        # Generate puzzle with shared game settings if available
-        if shared_settings:
-            # Each user gets different random words from the same wordlist source
-            wordlist_source = shared_settings.get("wordlist_source", "classic.txt")
-            spacer = shared_settings["puzzle_options"].get("spacer", 1)
-            may_overlap = shared_settings["puzzle_options"].get("may_overlap", False)
-            game_mode = shared_settings.get("game_mode", "classic")
-
-            # Override selected wordlist to match challenge
-            st.session_state.selected_wordlist = wordlist_source
-
-            # Generate puzzle with random words from the challenge's wordlist
-            words = load_word_list(wordlist_source)
-            puzzle = generate_puzzle(
-                grid_size=12,
-                words_by_len=words,
-                spacer=spacer,
-                may_overlap=may_overlap
-            )
-            st.session_state.game_mode = game_mode
-            st.session_state.spacer = spacer
-
-            # Users will see leaderboard showing all players' results
-            # Each player has their own uid and word_list in the users array
-        else:
-            # Normal game generation
-            words = load_word_list(st.session_state.get("selected_wordlist"))
-            puzzle = generate_puzzle(grid_size=12, words_by_len=words)
+        # Normal game generation
+        words = load_word_list(st.session_state.get("selected_wordlist"))
+        puzzle = generate_puzzle(grid_size=12, words_by_len=words)
 
         st.session_state.puzzle = puzzle
         st.session_state.grid_size = 12
@@ -141,10 +112,6 @@ def _init_session() -> None:
         if "show_incorrect_guesses" not in st.session_state:
             st.session_state.show_incorrect_guesses = True
 
-        # NEW: Initialize Show Challenge Share Links (default OFF)
-        if "show_challenge_share_links" not in st.session_state:
-            st.session_state.show_challenge_share_links = False
-    
         if "show_grid_ticks" not in st.session_state:
             st.session_state.show_grid_ticks = False
 
@@ -156,8 +123,6 @@ def _new_game() -> None:
          show_grid_ticks = st.session_state.get("show_grid_ticks", False)
          spacer = st.session_state.get("spacer",1)
          show_incorrect_guesses = st.session_state.get("show_incorrect_guesses", False)
-         # NEW: Preserve Show Challenge Share Links
-         show_challenge_share_links = st.session_state.get("show_challenge_share_links", False)
 
          st.session_state.clear()
          if selected:
@@ -167,8 +132,6 @@ def _new_game() -> None:
          st.session_state.show_grid_ticks = show_grid_ticks
          st.session_state.spacer = spacer
          st.session_state.show_incorrect_guesses = show_incorrect_guesses
-         # NEW: Restore Show Challenge Share Links
-         st.session_state.show_challenge_share_links = show_challenge_share_links
 
          st.session_state.radar_gif_path = None
          st.session_state.radar_gif_signature = None
@@ -207,106 +170,10 @@ def _sync_back(state: GameState) -> None:
 
 
 def _render_header():
-    st.title(f"Battlewords v{version}", anchor="title")
+    st.title(f"Battlewords", anchor="title") # removed v{version}
 
     st.subheader("Click the cells to reveal the letters of words on the grid. The radar screen pulses show the LAST letter of the six words. Guess the words for extra points and a better score!", anchor="subtitle")
 
-    # Only show Challenge Mode expander if in challenge mode and game_id is present
-    params = st.query_params if hasattr(st, "query_params") else {}
-    is_challenge_mode = "shared_game_settings" in st.session_state and "game_id" in params
-
-    if is_challenge_mode:
-        with st.expander("🎯 Challenge Mode (click to expand/collapse)", expanded=True):
-            shared_settings = st.session_state.get("shared_game_settings")
-            if shared_settings:
-                users = shared_settings.get("users", [])
-
-                if users:
-                    # Sort users by score (descending), then by time (ascending), then by difficulty (descending)
-                    def leaderboard_sort_key(u):
-                        # Use -score for descending, time for ascending, -difficulty for descending (default 0 if missing)
-                        diff = u.get("word_list_difficulty", 0)
-                        return (-u["score"], u["time"], -diff)
-
-                    sorted_users = sorted(users, key=leaderboard_sort_key)
-                    best_user = sorted_users[0]
-                    best_score = best_user["score"]
-                    best_time = best_user["time"]
-                    mins, secs = divmod(best_time, 60)
-                    best_time_str = f"{mins:02d}:{secs:02d}"
-
-                    # Build leaderboard HTML
-                    leaderboard_rows = []
-                    for i, user in enumerate(sorted_users[:5], 1):  # Top 5
-                        u_mins, u_secs = divmod(user["time"], 60)
-                        u_time_str = f"{u_mins:02d}:{u_secs:02d}"
-                        medal = ["🥇", "🥈", "🥉"][i-1] if i <= 3 else f"{i}."
-                        # show optional difficulty if present
-                        diff_str = ""
-                        if "word_list_difficulty" in user:
-                            try:
-                                diff_str = f" • diff {float(user['word_list_difficulty']):.2f}"
-                            except Exception:
-                                diff_str = ""
-                        leaderboard_rows.append(
-                            f"<div style='padding:0.25rem; font-size:0.85rem;'>{medal} {user['username']}: {user['score']} pts in {u_time_str}{diff_str}</div>"
-                        )
-                    leaderboard_html = "".join(leaderboard_rows)
-
-                    # Get the challenge SID from session state
-                    sid = st.session_state.get("loaded_game_sid")
-                    share_html = ""
-                    # NEW: Only render share link when setting enabled
-                    if sid and st.session_state.get("show_challenge_share_links", False):
-                        share_url = get_shareable_url(sid)
-                        share_html = f"<div style='margin-top:1rem;margin-bottom:0.5rem;font-size: 0.9rem;'><a href='{share_url}' target='_blank' style='color:#FFF;text-decoration:underline;'><strong>🔗 Share this challenge</a></strong<br/><br/><span style='font-size:0.85em;color:#ddd;'>{share_url}</span>"
-
-                    st.markdown(
-                        f"""
-                        <div style="
-                            background: linear-gradient(90deg, #1d64c8 0%, #165ba8 100%);
-                            color: white;
-                            padding: 1rem;
-                            border-radius: 0.5rem;
-                            margin-bottom: 1rem;
-                            text-align: center;
-                            box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
-                        ">
-                            🎯 <strong>CHALLENGE MODE</strong> 🎯<br/>
-                            <span style="font-size: 0.9rem;">
-                                Beat the best: <strong>{best_score} points</strong> in <strong>{best_time_str}</strong> by <strong>{best_user['username']}</strong>
-                            </span>
-                            <div style="margin-top:0.75rem; border-top: 1px solid rgba(255,255,255,0.3); padding-top:0.5rem;">
-                                <strong style="font-size:0.9rem;">🏆 Leaderboard</strong>
-                                {leaderboard_html}
-                            </div>
-                            {share_html}
-                        </div>
-                        """,
-                        unsafe_allow_html=True
-                    )
-                else:
-                    st.markdown(
-                        """
-                        <div style="
-                            background: linear-gradient(90deg, #1d64c8 0%, #165ba8 100%);
-                            color: white;
-                            padding: 1rem;
-                            border-radius: 0.5rem;
-                            margin-bottom: 1rem;
-                            text-align: center;
-                            box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
-                        ">
-                            🎯 <strong>CHALLENGE MODE</strong> 🎯<br/>
-                            <span style="font-size: 0.9rem;">
-                                Be the first to complete this challenge!
-                            </span>
-                        </div>
-                        """,
-                        unsafe_allow_html=True
-                    )
-
-
     inject_styles()
 
 
@@ -1132,8 +999,6 @@ def _game_over_content(state: GameState) -> None:
               /*filter: invert(1);*/
            }
            .st-bb {background-color: rgba(29, 100, 200, 0.5);} 
-           .st-key-generate_share_link div[data-testid="stButton"] button { aspect-ratio: auto;} 
-           .st-key-generate_share_link div[data-testid="stButton"] button:hover { color: #1d64c8;}
         </style>
         """,
         unsafe_allow_html=True,
@@ -1180,164 +1045,8 @@ def _game_over_content(state: GameState) -> None:
         height=0,
     )
 
-    # Share Challenge Button
-    st.markdown("---")
-
-    # Style the containing Streamlit block via CSS :has() using an anchor inside this container
-    with st.container(key="share-challenge"):
-        st.markdown(
-            """
-            <style>
-              .st-key-share-challenge{ display:none;}
-              /* Apply the dialog background to the Streamlit block that contains our anchor */
-              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) {                
-                border-radius: 1rem;
-                box-shadow: 0 0 32px #1d64c8;
-                background: linear-gradient(-45deg, #1d64c8, #ffffff, #1d64c8, #666666);
-                color: #fff;
-                padding: 16px;
-              }
-              /* Improve inner text contrast inside the styled block */
-              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) h3,
-              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) label,
-              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) p {
-                color: #fff !important;
-              }
-              /* Ensure code block is readable */
-              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) pre,
-              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) code {
-                background: rgba(0,0,0,0.25) !important;
-                color: #fff !important;
-              }
-              /* Buttons hover contrast */
-              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) button:hover {
-                filter: brightness(1.1);
-              }
-            </style>
-            <div id="bw-share-anchor"></div>
-            """,
-            unsafe_allow_html=True,
-        )
-
-        st.markdown("### 🎮 Share Your Challenge")
-
-        # Check if this is a shared game being completed
-        is_shared_game = st.session_state.get("loaded_game_sid") is not None
-        existing_sid = st.session_state.get("loaded_game_sid")
-
-        # Username input
-        if "player_username" not in st.session_state:
-            st.session_state["player_username"] = ""
-
-        username = st.text_input(
-            "Enter your name (optional)",
-            value=st.session_state.get("player_username", ""),
-            key="username_input",
-            placeholder="Anonymous"
-        )
-        if username:
-            st.session_state["player_username"] = username
-        else:
-            username = "Anonymous"
-
-        # Check if share URL already generated
-        if "share_url" not in st.session_state or st.session_state.get("share_url") is None:
-            button_text = "📊 Submit Your Result" if is_shared_game else "🔗 Generate Share Link"
-
-            if st.button(button_text, key="generate_share_link", use_container_width=True):
-                try:
-                    # Extract game data
-                    word_list = [w.text for w in state.puzzle.words]
-                    spacer = state.puzzle.spacer
-                    may_overlap = state.puzzle.may_overlap
-                    wordlist_source = st.session_state.get("selected_wordlist", "unknown")
-
-                    if is_shared_game and existing_sid:
-                        # Add result to existing game
-                        success = add_user_result_to_game(
-                            sid=existing_sid,
-                            username=username,
-                            word_list=word_list,  # Each user gets different words
-                            score=state.score,
-                            time_seconds=elapsed_seconds
-                        )
-
-                        if success:
-                            share_url = get_shareable_url(existing_sid)
-                            st.session_state["share_url"] = share_url
-                            st.session_state["share_sid"] = existing_sid
-                            st.success(f"✅ Result submitted for {username}!")
-                            st.rerun()
-                        else:
-                            st.error("Failed to submit result")
-                    else:
-                        # Create new game
-                        challenge_id, full_url, sid = save_game_to_hf(
-                            word_list=word_list,
-                            username=username,
-                            score=state.score,
-                            time_seconds=elapsed_seconds,
-                            game_mode=state.game_mode,
-                            grid_size=state.grid_size,
-                            spacer=spacer,
-                            may_overlap=may_overlap,
-                            wordlist_source=wordlist_source
-                        )
-
-                        if sid:
-                            share_url = get_shareable_url(sid)
-                            st.session_state["share_url"] = share_url
-                            st.session_state["share_sid"] = sid
-                            st.rerun()
-                        else:
-                            st.error("Failed to generate short URL")
-
-                except Exception as e:
-                    st.error(f"Failed to save game: {e}")
-        else:
-            # Conditionally display the generated share URL
-            if st.session_state.get("show_challenge_share_links", False):
-                # Display generated share URL
-                share_url = st.session_state["share_url"]
-                st.success("✅ Share link generated!")
-                st.code(share_url, language=None)
-
-                # More robust copy-to-clipboard implementation with fallbacks
-                import json as _json
-                import html as _html
-
-                _share_url_json = _json.dumps(share_url)  # safe for JS
-                _share_url_attr = _html.escape(share_url, quote=True)  # safe for HTML attribute
-                _share_url_text = _html.escape(share_url)
-
-                components.html(
-                    f"""
-                    <div id="bw-copy-container" style="
-                        display:flex;
-                        gap:8px;
-                        width:100%;
-                        align-items:center;
-                        margin-top:6px;
-                        justify-content:center;
-                    ">
-                    
-                    <strong><a href="{_share_url_attr}"
-                        target="_blank" 
-                        rel="noopener noreferrer"
-                        style="text-decoration: underline; color: #fff; word-break: break-all; filter: drop-shadow(1px 1px 2px #003);">
-                    {_share_url_text}
-                    </a></strong>
-                    </div>
-                    """,
-                    height=80
-                )
-            else:
-                # Do not display the share URL, but confirm it’s saved/submitted
-                st.success("✅ Your result has been saved.")
-
-    st.markdown("---")
-
     # Dialog actions
+    st.markdown("---")
     if st.button("Close", key="close_game_over"):
         st.session_state["show_gameover_overlay"] = False
         st.rerun()
@@ -1366,56 +1075,8 @@ def _render_game_over(state: GameState):
         if visible:
             _game_over_dialog(state)
 
-def _on_game_option_change() -> None:
-    """
-    Unified callback for game option changes.
-    If currently in a loaded challenge, break the link by resetting challenge mode
-    and removing the game_id query param. Then start a new game with the updated options.
-    """
-    try:
-        # Remove challenge-specific query param if present
-        if hasattr(st, "query_params"):
-            qp = st.query_params
-            # st.query_params may be a Mapping; pop safely if supported
-            try:
-                if "game_id" in qp:
-                    qp.pop("game_id")
-            except Exception:
-                # Fallback: clear all params if pop not supported
-                try:
-                    st.query_params.clear()
-                except Exception:
-                    pass
-    except Exception:
-        pass
-
-    # Clear challenge session flags and links
-    if st.session_state.get("loaded_game_sid") is not None:
-        st.session_state.loaded_game_sid = None
-    # Remove loaded challenge settings so UI no longer treats session as challenge mode
-    st.session_state.pop("shared_game_settings", None)
-    # Ensure the loader won't auto-reload challenge on rerun within this session
-    st.session_state["shared_game_loaded"] = True
-
-    # Clear any existing generated share link tied to the previous challenge
-    st.session_state.pop("share_url", None)
-    st.session_state.pop("share_sid", None)
-
-    # Start a fresh game with updated options
-    _new_game()
-
 def run_app():
     start_root_fade_in(0.0)
-    # Render PWA service worker registration (meta tags in <head> via Docker)
-    # Streamlit reruns the script frequently; inject this only once per session.
-    if not st.session_state.get("pwa_injected", False):
-        st.markdown(pwa_service_worker, unsafe_allow_html=True)
-        st.session_state["pwa_injected"] = True
-
-    # try:
-    #     st.set_page_config(initial_sidebar_state="collapsed")
-    # except Exception:
-    #     pass
 
     # Handle query params using new API
     try:
@@ -1438,42 +1099,9 @@ def run_app():
         with CustomSpinner(spinner_placeholder, "Initial Load..."):
             st.session_state["initial_page_loaded"] = True
 
-    # Basic branch: only render the play experience
-    # Settings and leaderboard pages are disabled
-
-    # Handle game_id for loading shared games
-    if "game_id" in params and "shared_game_loaded" not in st.session_state:
-        sid = params.get("game_id")
-        spinner_placeholder = st.empty()
-        with CustomSpinner(spinner_placeholder, "Loading challenge..."):
-            try:
-                settings = load_game_from_sid(sid)
-                if settings:
-                    st.session_state["shared_game_settings"] = settings
-                    st.session_state["loaded_game_sid"] = sid
-                    st.session_state["shared_game_loaded"] = True
-
-                    # Get best score and time from users array
-                    users = settings.get("users", [])
-                    if users:
-                        best_score = max(u["score"] for u in users)
-                        best_time = min(u["time"] for u in users)
-                        st.toast(
-                            f"🎯 Loading shared challenge (Best: {best_score} pts in {best_time}s by {len(users)} player(s))",
-                            icon="ℹ️",
-                        )
-                    else:
-                        st.toast("🎯 Loading shared challenge", icon="ℹ️")
-                else:
-                    st.warning(f"No shared game found for ID: {sid}. Starting a normal game.")
-                    st.session_state["shared_game_loaded"] = True
-            except Exception as e:
-                st.error(f"❌ Error loading shared game: {e}")
-                st.session_state["shared_game_loaded"] = True
-
-        # Show spinner during game initialization
+    # Basic branch: challenge mode and shared games are disabled
 
-    if st.session_state.get("needs_initialization", True):        
+    if st.session_state.get("needs_initialization", True):
         spinner_placeholder = st.empty()
         with CustomSpinner(spinner_placeholder, "Initializing Game..."):
             st.session_state.needs_initialization = False
@@ -1491,6 +1119,14 @@ def run_app():
     state = _to_state()
     if is_game_over(state) and not st.session_state.get("hide_gameover_overlay", False):
         _render_game_over(state)
+
+    # Version info footer (hidden when ?nofooter is present)
+    if not params.get("nofooter"):
+        st.markdown(
+            f'<div style="text-align:center;">{versions_html()}</div>',
+            unsafe_allow_html=True,
+        )
+
     finish_root_fade_in(2.0)
 
 def _render_game_tab():

battlewords/ui_helpers.py

@@ -22,152 +22,19 @@ def fig_to_pil_rgba(fig):
 def get_effective_game_title() -> str:
     """
     Get the effective game title, prioritizing:
-    1. Challenge-specific game_title from shared_game_settings
-    2. Session state game_title (if set)
-    3. APP_SETTINGS default
-    4. Fallback to "Wrdler"
+    1. Session state game_title (if set)
+    2. APP_SETTINGS default
+    3. Fallback to "Battlewords"
     Returns:
         str: The effective game title.
     """
-    # First check shared game settings (challenge mode)
-    shared_settings = st.session_state.get("shared_game_settings")
-    if shared_settings and shared_settings.get("game_title"):
-        return shared_settings["game_title"]
-    
-    # Then check session state
+    # Check session state
     if st.session_state.get("game_title"):
         return st.session_state["game_title"]
     
     # Fall back to APP_SETTINGS
     return APP_SETTINGS.get("game_title", "Battlewords")
 
-# PWA (Progressive Web App) Support
-# Enables installing BattleWords as a native-feeling mobile app
-# Note: PWA meta tags are injected into <head> via Docker build (inject-pwa-head.sh)
-# This ensures proper PWA detection by browsers
-pwa_service_worker = """
-<script>
-// Register service worker for offline functionality
-// Note: Using inline Blob URL to bypass Streamlit's text/plain content-type for .js files
-if ('serviceWorker' in navigator) {
-  window.addEventListener('load', () => {
-    // Service worker code as string (inline to avoid MIME type issues)
-    const swCode = `
-const CACHE_NAME = 'battlewords-v0.2.29';
-const RUNTIME_CACHE = 'battlewords-runtime';
-
-const PRECACHE_URLS = [
-  '/',
-  '/app/static/manifest.json',
-  '/app/static/icon-192.png',
-  '/app/static/icon-512.png'
-];
-
-self.addEventListener('install', event => {
-  console.log('[ServiceWorker] Installing...');
-  event.waitUntil(
-    caches.open(CACHE_NAME)
-      .then(cache => {
-        console.log('[ServiceWorker] Precaching app shell');
-        return cache.addAll(PRECACHE_URLS);
-      })
-      .then(() => self.skipWaiting())
-  );
-});
-
-self.addEventListener('activate', event => {
-  console.log('[ServiceWorker] Activating...');
-  event.waitUntil(
-    caches.keys().then(cacheNames => {
-      return Promise.all(
-        cacheNames.map(cacheName => {
-          if (cacheName !== CACHE_NAME && cacheName !== RUNTIME_CACHE) {
-            console.log('[ServiceWorker] Deleting old cache:', cacheName);
-            return caches.delete(cacheName);
-          }
-        })
-      );
-    }).then(() => self.clients.claim())
-  );
-});
-
-self.addEventListener('fetch', event => {
-  if (event.request.method !== 'GET') return;
-  if (!event.request.url.startsWith('http')) return;
-
-  event.respondWith(
-    caches.open(RUNTIME_CACHE).then(cache => {
-      return fetch(event.request)
-        .then(response => {
-          if (response.status === 200) {
-            cache.put(event.request, response.clone());
-          }
-          return response;
-        })
-        .catch(() => {
-          return caches.match(event.request).then(cachedResponse => {
-            if (cachedResponse) {
-              console.log('[ServiceWorker] Serving from cache:', event.request.url);
-              return cachedResponse;
-            }
-            return new Response('Offline - Please check your connection', {
-              status: 503,
-              statusText: 'Service Unavailable',
-              headers: new Headers({'Content-Type': 'text/plain'})
-            });
-          });
-        });
-    })
-  );
-});
-
-self.addEventListener('message', event => {
-  if (event.data.action === 'skipWaiting') {
-    self.skipWaiting();
-  }
-});
-`;
-
-    // Create Blob URL for service worker
-    const blob = new Blob([swCode], { type: 'application/javascript' });
-    const swUrl = URL.createObjectURL(blob);
-
-    navigator.serviceWorker.register(swUrl)
-      .then(registration => {
-        console.log('[PWA] Service Worker registered successfully:', registration.scope);
-
-        registration.addEventListener('updatefound', () => {
-          const newWorker = registration.installing;
-          newWorker.addEventListener('statechange', () => {
-            if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
-              console.log('[PWA] New version available! Refresh to update.');
-            }
-          });
-        });
-      })
-      .catch(error => {
-        console.log('[PWA] Service Worker registration failed:', error);
-      });
-  });
-}
-
-// Prompt user to install PWA (for browsers that support it)
-let deferredPrompt;
-window.addEventListener('beforeinstallprompt', (e) => {
-  console.log('[PWA] Install prompt available');
-  e.preventDefault();
-  deferredPrompt = e;
-  // Could show custom install button here if desired
-});
-
-// Track when user installs the app
-window.addEventListener('appinstalled', () => {
-  console.log('[PWA] BattleWords installed successfully!');
-  deferredPrompt = null;
-});
-</script>
-"""
-
 
 ocean_background_css = """
 <style>
@@ -591,90 +458,6 @@ def inject_styles() -> None:
         unsafe_allow_html=True,
     )
 
-# --- Footer Navigation ---
-def render_footer(current_page: str = "play", params: dict = {}) -> None:
-    """Render footer navigation.
-
-    Args:
-        current_page: Active page key ("play", "leaderboard", "settings").
-    """
-
-    # If nofooter=1 is present, do not render the footer
-    if isinstance(params, dict) and params.get("nofooter") == "1":
-        return
-
-    play_active = "active" if current_page == "play" else ""
-    leaderboard_active = "active" if current_page == "leaderboard" else ""
-    settings_active = "active" if current_page == "settings" else ""
-
-    game_id: Optional[str] = None
-    if isinstance(params, dict):
-        game_id = params.get("game_id")
-    if not game_id:
-        game_id = st.session_state.get("loaded_game_sid")
-
-    def _url(page: str) -> str:
-        base = f"?page={page}"
-        if game_id:
-            return f"{base}&game_id={game_id}"
-        return base
-
-    st.markdown(
-        f"""
-        <style>
-        .bw-footer {{
-            position: fixed;
-            bottom: 0;
-            left: 0;
-            right: 0;
-            background: linear-gradient(180deg, transparent 0%, rgba(11, 42, 74, 0.95) 30%, rgba(11, 42, 74, 0.98) 100%);
-            padding: 0.75rem 1rem 0.5rem;
-            z-index: 9998;
-            text-align: center;
-        }}
-        .bw-footer-nav {{
-            display: flex;
-            justify-content: center;
-            align-items: center;
-            gap: 1rem;
-            flex-wrap: wrap;
-        }}
-        .bw-footer-nav a {{
-            color: #d7faff;
-            text-decoration: none;
-            font-weight: 600;
-            font-size: 0.9rem;
-            padding: 0.4rem 0.8rem;
-            border-radius: 0.5rem;
-            background: rgba(29, 100, 200, 0.3);
-            border: 1px solid rgba(215, 250, 255, 0.3);
-            transition: all 0.2s ease;
-        }}
-        .bw-footer-nav a:hover {{
-            background: rgba(29, 100, 200, 0.6);
-            border-color: rgba(215, 250, 255, 0.6);
-            color: #ffffff;
-            text-decoration: none;
-        }}
-        .bw-footer-nav a.active {{
-            background: rgba(32, 212, 108, 0.3);
-            border-color: rgba(32, 212, 108, 0.5);
-        }}
-        .stMainBlockContainer {{
-            padding-bottom: 60px !important;
-        }}
-        </style>
-        <div class="bw-footer">
-            <nav class="bw-footer-nav">
-                <a href="{_url('play')}" target="_self" class="{play_active}">Play</a>
-                <a href="{_url('leaderboard')}" target="_self" class="{leaderboard_active} hide">Leaderboard</a>
-                <a href="{_url('settings')}" target="_self" class="{settings_active} hide">Settings</a>
-            </nav>
-        </div>
-        """,
-        unsafe_allow_html=True,
-    )
-
 
 # --- Spinner Overlay ---
 def show_spinner(message: str = "Loading..."):

claude.md

@@ -1,413 +1,67 @@
-# BattleWords - Project Context
+# BattleWords - Project Context (Basic Branch)
 
 ## Project Overview
-BattleWords is a vocabulary learning game inspired by Battleship mechanics, built with Streamlit and Python 3.12. Players reveal cells on a 12x12 grid to discover hidden words and earn points for strategic guessing.
+BattleWords is a vocabulary learning game inspired by Battleship mechanics, built with Streamlit and Python. Players reveal cells on a 12×12 grid to discover hidden words.
 
-**Current Version:** 0.2.37 (Stable - User Features, UI Enhancements)
-**Last Updated:** 2026-02-10
-**Next Version:** 0.3.0 (In Development - Wrdler improvements)
+**Current Version:** 0.2.37 BASIC
+**Branch:** `basic`
+**Last Updated:** 2026-02-11
 **Repository:** https://github.com/Oncorporation/BattleWords.git
-**Live Demo:** https://huggingface.co/spaces/Surn/BattleWords
 
-## Current Upgrades (Wrdler → BattleWords)
-
-The detailed porting checklist lives in `specs/upgrade.mdx`.
-
-## Recent Changes
-See `README.md` for the canonical release notes: [Recent Changes](README.md#recent-changes)
+This file describes the intended scope of the `basic` branch only.
 
 ## Core Gameplay
-- 12x12 grid with 6 hidden words (2×4-letter, 2×5-letter, 2×6-letter)
-- Words placed horizontally or vertically, no overlaps
+- 12×12 grid with 6 hidden words (2×4-letter, 2×5-letter, 2×6-letter)
+- Words placed horizontally or vertically
 - 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 (v0.2.20+):** Challenge Mode with game sharing via short URLs
-- **✅ IMPLEMENTED (v0.2.20+):** Remote storage via Hugging Face datasets for challenges and leaderboards
-- **✅ IMPLEMENTED (v0.2.28):** PWA install support
-- **PLANNED (v0.3.0):** Local persistent storage for individual player results and high scores
 
 ### Scoring Tiers
-- **Legendary:** 46+ points (perfect game)
-- **Fantastic:** 42-45 points
-- **Great:** 38-41 points
-- **Good:** 34-37 points
-- **Keep practicing:** < 34 points
-
-## Technical Architecture
-
-### Technology Stack
-- **Framework:** Streamlit 1.52.1
-- **Language:** Python 3.12.8
-- **Visualization:** Matplotlib, NumPy
-- **Data Processing:** Pandas, Altair
-- **Storage:** JSON-based local persistence
-- **Testing:** Pytest
-- **Code Quality:** Flake8, MyPy
-- **Package Manager:** UV (modern Python package manager)
-
-### Project Structure
+- Legendary: 46+
+- Fantastic: 42–45
+- Great: 38–41
+- Good: 34–37
+
+## UI / UX (Basic)
+- Single play experience rendered from `app.py`
+- No sidebar
+- No footer navigation
+- No query-param routing to non-game pages
+- `CustomSpinner` is used for smooth transitions (initial load, New Game, Game Over)
+- Radar visualization rendered via matplotlib and saved as GIF
+
+## Word Lists
+- Loaded only from local files in `battlewords/words/`
+- No AI-generated / model-backed word list generation
+
+## Tech Stack
+- Python 3.10+
+- Streamlit
+- matplotlib
+- numpy
+- Pillow
+
+## Out of Scope (Basic)
+- Challenge mode / remote storage / share links
+- PWA support
+- Audio (music and sound effects)
+- Settings page
+- Leaderboard
+- Tests
+
+## Project Structure (Relevant)
 ```
 battlewords/
 ├── app.py                    # Streamlit entry point
 ├── battlewords/              # Main package
-│   ├── __init__.py          # Version: 0.2.33
-│   ├── 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 (~1800 lines)
-│   ├── 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 (v0.1.0)
-│   ├── version_info.py      # Version display
-│   ├── settings_page.py      # Settings page renderer (query-param routing)
-│   ├── ui_helpers.py         # Footer navigation + shared UI helpers
-│   ├── modules/             # Shared utility modules (from OpenBadge)
-│   │   ├── __init__.py      # Module exports
-│   │   ├── storage.py       # HuggingFace storage & URL shortener (v0.1.5)
-│   │   ├── 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
-├── specs/                   # Documentation
-│   ├── specs.md             # Game specifications
-│   ├── requirements.md      # Implementation requirements
-│   └── history.md           # Game history
-├── .env                     # Environment variables
-├── pyproject.toml          # Project metadata
-├── requirements.txt        # Dependencies
-├── uv.lock                 # UV lock file
-├── Dockerfile              # Container deployment
-└── CLAUDE.md               # This file - project context for Claude
-```
-
-## 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
-- **Animated Radar:** Pulsing rings showing word boundaries (last letter locations)
-- **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
-  - "Show Challenge Share Links" toggle (default OFF) to control URL visibility
-  - Each player gets different random words from the same wordlist
-
-### PLANNED: Local Player Storage (v0.3.0)
-- **Local Storage:**
-  - Location: `~/.battlewords/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
-- Deterministic seeding support for reproducible puzzles
-- Configurable word spacing (spacer: 0-2)
-  - 0: Words may touch
-  - 1: At least 1 blank cell between words (default)
-  - 2: At least 2 blank cells between words
-- Validation ensures no overlaps, proper bounds, correct word distribution
-
-### UI Components (Current)
-- **Radar Visualization:** Animated matplotlib GIF showing word boundaries
-  - Displays pulsing rings at last letter of each word
-  - Hides rings for guessed words
-  - Three-layer composition: gradient background, scope image, animated rings
-  - Cached per-puzzle with signature matching
-- **Game Grid:** Interactive 12x12 button grid with responsive layout
-- **Score Panel:** Compact score table (timer display removed)
-- **Routing/Navigation:** Query-param routing via `?page=play|settings|leaderboard`
-- **Footer Navigation:** Primary navigation is in the footer (links may be conditionally hidden)
-- **Settings:** Dedicated settings page renderer (not a sidebar panel)
-- **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 (v0.2.20+):**
-  - 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
-  - Conditional share URL visibility toggle
-- **PLANNED (v0.3.0):** Local high scores expander in sidebar
-- **PLANNED (v0.3.0):** Personal statistics display
-
-### Recent Changes & Branch Status
-**Branch:** hugs
-
-**Latest (v0.2.17):**
-- Documentation updates and corrections
-  - Updated CLAUDE.md with accurate feature status
-  - Clarified v0.3.0 planned features vs current implementation
-  - Added comprehensive project structure details
-  - Improved version tracking and roadmap clarity
-
-**Previously Fixed (v0.2.16):**
-- Replace question marks with underscores in score panel
-- Add toggle for incorrect guess history display (enabled by default)
-- Game over popup positioning improvements
-- Music playback after game end
-- Sound effect and music volume issues
-- Radar alignment inconsistencies
-  - Added `fig.subplots_adjust(left=0, right=0.9, top=0.9, bottom=0)`
-  - Set `fig.patch.set_alpha(0.0)` for transparent background
-  - Maintains 2% margin for tick visibility while ensuring consistent layer alignment
-
-**Completed (v0.2.20-0.2.27 - Challenge Mode):**
-- ✅ Imported storage modules from OpenBadge project:
-  - `battlewords/modules/storage.py` (v0.1.5) - HuggingFace storage & URL shortener
-  - `battlewords/modules/constants.py` (trimmed) - Storage-related constants
-  - `battlewords/modules/file_utils.py` - File utility functions
-  - `battlewords/modules/storage.md` - Documentation
-- ✅ Created `battlewords/game_storage.py` (v0.1.0) - BattleWords storage wrapper:
-  - `save_game_to_hf()` - Save game to HF repo and generate short URL
-  - `load_game_from_sid()` - Load game from short ID
-  - `generate_uid()` - Generate unique game identifiers
-  - `serialize_game_settings()` - Convert game data to JSON
-  - `get_shareable_url()` - Generate shareable URLs
-  - `add_user_result_to_game()` - Append results to existing challenges
-- ✅ UI integration complete (`battlewords/ui.py`):
-  - Query parameter parsing for `?game_id=<sid>` on app load
-  - Load shared game settings into session state
-  - Challenge Mode banner with leaderboard (top 5)
-  - Share button in game over dialog with "Generate Share Link" or "Submit Result"
-  - Conditional share URL display based on settings toggle
-  - Automatic save to HuggingFace on game completion
-  - Word list difficulty calculation and display
-- ✅ Generator updates (`battlewords/generator.py`):
-  - Added `target_words` parameter for loading specific words
-  - Added `may_overlap` parameter (for future crossword mode)
-  - Support for shared game replay with randomized word positions
-
-**In Progress (v0.3.0 - Local Player History):**
-- ⏳ Local storage module (`battlewords/local_storage.py`)
-- ⏳ Personal high score tracking (local JSON files)
-- ⏳ High score sidebar UI display
-- ⏳ Player statistics tracking and display
-
-## 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]
-    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
-```bash
-# 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
-```bash
-docker build -t battlewords .
-docker run -p 8501:8501 battlewords
-```
-
-### Testing
-```bash
-pytest tests/
-```
-
-### Environment Variables (for Challenge Mode)
-Challenge Mode requires HuggingFace Hub access for remote storage. Create a `.env` file in the project root:
-
-```bash
-# Required for Challenge Mode
-HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx  # or HF_TOKEN
-HF_REPO_ID=YourUsername/YourRepo       # Target HF dataset repo
-SPACE_NAME=YourUsername/BattleWords    # Your HF Space name
-
-# Optional
-CRYPTO_PK=                             # Reserved for future signing
+│   ├── __init__.py
+│   ├── models.py             # Data models
+│   ├── generator.py          # Puzzle generation
+│   ├── logic.py              # Reveal/guess/scoring
+│   ├── ui.py                 # Streamlit UI
+│   ├── ui_helpers.py         # Styles + transitions
+│   └── words/                # Local word lists
+└── specs/                    # Documentation
 ```
-
-**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:** cc-01
-**Purpose:** Storage and sharing features (v0.3.0 development)
-**Main Branch:** main (not specified in git config, but typical convention)
-
-### Remotes
-- **ONCORP (origin):** https://github.com/Oncorporation/BattleWords.git (main repository)
-- **Hugging:** https://huggingface.co/spaces/Surn/BattleWords (live deployment)
-
-## Known Issues
-- Word list loading bug: App may not select proper word lists in some environments
-  - Investigation needed in `word_loader.get_wordlist_files()` and `load_word_list()`
-  - Sidebar selection persistence needs verification
-
-## v0.3.0 Development Status (cc-01 branch)
-
-### Completed ✅
-- `battlewords/storage.py` module created with:
-  - `GameStorage` class for JSON-based local storage
-  - `GameResult` and `HighScoreEntry` dataclasses
-  - Functions: `generate_game_id_from_words()`, `parse_game_id_from_url()`, `create_shareable_url()`
-  - Storage location: `~/.battlewords/data/` (game_results.json, highscores.json)
-- Documentation updated in specs/ folder
-
-### In Progress ⏳
-- Puzzle model integration for game_id field
-- Generator updates for `target_words` parameter (replay from game_id)
-- UI integration:
-  - Storage calls on game completion
-  - High score display in sidebar
-  - Share button in game over dialog
-  - Query parameter parsing for game_id
-  - Player name input in sidebar
-
-### Planned 📋
-- Unit tests for storage module
-- Integration tests for complete storage flow
-- Game replay from shared ID functionality
-- Player statistics display
-- Share results text generation
-
-## Future Roadmap
-
-### Phase 1.5 (v0.3.0) - Current Focus ⏳
-- ✅ Storage module with local JSON persistence (backend complete)
-- ✅ Game ID generation system (backend complete)
-- ⏳ High score tracking and display (backend complete, UI pending)
-- ⏳ Share challenge functionality (UI integration pending)
-- ⏳ Game replay from shared IDs (generator updates needed)
-- ⏳ Player name input and statistics
-
-### Beta (v0.5.0)
-- Word overlaps on shared letters (crossword-style gameplay)
-- Enhanced responsive layout for mobile/tablet
-- Keyboard navigation and guessing
-- Deterministic seed UI for custom puzzles
-- Improved accessibility features
-
-### Full (v1.0.0)
-- Optional cloud storage backend (FastAPI)
-- Daily puzzle mode with global leaderboards
-- Practice mode with hints
-- Enhanced UX features (animations, themes)
-- Multiple difficulty levels
-- Internationalization (i18n) support
-
-## Deployment Targets
-- **Hugging Face Spaces:** Primary deployment platform
-- **Docker:** Containerized deployment for any platform
-- **Local:** Development and testing
-
-### Privacy & Data
-- All storage is local (no telemetry)
-- Player names optional
-- No data leaves user's machine
-- Easy to delete: just remove `~/.battlewords/data/`
-
-## Notes for Claude
-- Project uses modern Python features (3.12+)
-- Heavy use of Streamlit session state for game state management
-- Matplotlib figures are converted to PIL images and animated GIFs
-- Client-side JavaScript for timer updates without page refresh
-- CSS heavily customized for game aesthetics
-- All file paths should be absolute when working in WSL environment
-- Current working directory: `/mnt/d/Projects/Battlewords`
-- Storage features are backward-compatible (game works without storage)
-- Game IDs are deterministic for consistent sharing
-- JSON storage chosen for simplicity and privacy
-
-### 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+ but can run on 3.10+.

generate_pwa_icons.py

@@ -1,98 +0,0 @@
-#!/usr/bin/env python3
-"""
-Generate PWA icons for BattleWords.
-Creates 192x192 and 512x512 icons with ocean theme and 'BW' text.
-"""
-
-from PIL import Image, ImageDraw, ImageFont
-import os
-
-def create_icon(size, filename):
-    """Create a square icon with ocean gradient background and 'BW' text."""
-
-    # Create image with ocean blue gradient
-    img = Image.new('RGB', (size, size))
-    draw = ImageDraw.Draw(img)
-
-    # Draw vertical gradient (ocean theme)
-    water_sky = (29, 100, 200)    # #1d64c8
-    water_deep = (11, 42, 74)     # #0b2a4a
-
-    for y in range(size):
-        # Interpolate between sky and deep
-        ratio = y / size
-        r = int(water_sky[0] * (1 - ratio) + water_deep[0] * ratio)
-        g = int(water_sky[1] * (1 - ratio) + water_deep[1] * ratio)
-        b = int(water_sky[2] * (1 - ratio) + water_deep[2] * ratio)
-        draw.rectangle([(0, y), (size, y + 1)], fill=(r, g, b))
-
-    # Draw circular background for better icon appearance
-    circle_margin = size // 10
-    circle_bbox = [circle_margin, circle_margin, size - circle_margin, size - circle_margin]
-
-    # Draw white circle with transparency
-    overlay = Image.new('RGBA', (size, size), (255, 255, 255, 0))
-    overlay_draw = ImageDraw.Draw(overlay)
-    overlay_draw.ellipse(circle_bbox, fill=(255, 255, 255, 40))
-
-    # Composite the overlay
-    img = img.convert('RGBA')
-    img = Image.alpha_composite(img, overlay)
-
-    # Draw 'BW' text
-    font_size = size // 3
-    try:
-        # Try to load a nice bold font
-        font = ImageFont.truetype("/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", font_size)
-    except Exception:
-        try:
-            # Fallback for Windows
-            font = ImageFont.truetype("C:/Windows/Fonts/arialbd.ttf", font_size)
-        except Exception:
-            # Ultimate fallback
-            font = ImageFont.load_default()
-
-    draw = ImageDraw.Draw(img)
-    text = "BW"
-
-    # Get text bounding box for centering
-    bbox = draw.textbbox((0, 0), text, font=font)
-    text_width = bbox[2] - bbox[0]
-    text_height = bbox[3] - bbox[1]
-
-    # Center the text
-    x = (size - text_width) // 2
-    y = (size - text_height) // 2 - (bbox[1] // 2)
-
-    # Draw text with shadow for depth
-    shadow_offset = size // 50
-    draw.text((x + shadow_offset, y + shadow_offset), text, fill=(0, 0, 0, 100), font=font)
-    draw.text((x, y), text, fill='white', font=font)
-
-    # Convert back to RGB for saving as PNG
-    if img.mode == 'RGBA':
-        background = Image.new('RGB', img.size, (11, 42, 74))
-        background.paste(img, mask=img.split()[3])  # Use alpha channel as mask
-        img = background
-
-    # Save
-    img.save(filename, 'PNG', optimize=True)
-    print(f"[OK] Created {filename} ({size}x{size})")
-
-def main():
-    """Generate both icon sizes."""
-    script_dir = os.path.dirname(os.path.abspath(__file__))
-    static_dir = os.path.join(script_dir, 'battlewords', 'static')
-
-    # Ensure directory exists
-    os.makedirs(static_dir, exist_ok=True)
-
-    # Generate icons
-    print("Generating PWA icons for BattleWords...")
-    create_icon(192, os.path.join(static_dir, 'icon-192.png'))
-    create_icon(512, os.path.join(static_dir, 'icon-512.png'))
-    print("\n[SUCCESS] PWA icons generated successfully!")
-    print(f"   Location: {static_dir}")
-
-if __name__ == '__main__':
-    main()

inject-pwa-head.sh

@@ -1,49 +0,0 @@
-#!/bin/bash
-# Inject PWA meta tags into Streamlit's index.html head section
-# This script modifies the Streamlit index.html during Docker build
-
-set -e
-
-echo "[PWA] Injecting PWA meta tags into Streamlit's index.html..."
-
-# Find Streamlit's index.html
-STREAMLIT_INDEX=$(python3 -c "import streamlit; import os; print(os.path.join(os.path.dirname(streamlit.__file__), 'static', 'index.html'))")
-
-if [ ! -f "$STREAMLIT_INDEX" ]; then
-    echo "[PWA] ERROR: Streamlit index.html not found at: $STREAMLIT_INDEX"
-    exit 1
-fi
-
-echo "[PWA] Found Streamlit index.html at: $STREAMLIT_INDEX"
-
-# Check if already injected (to make script idempotent)
-if grep -q "PWA (Progressive Web App) Meta Tags" "$STREAMLIT_INDEX"; then
-    echo "[PWA] PWA tags already injected, skipping..."
-    exit 0
-fi
-
-# Read the injection content
-INJECT_FILE="/app/pwa-head-inject.html"
-if [ ! -f "$INJECT_FILE" ]; then
-    echo "[PWA] ERROR: Injection file not found at: $INJECT_FILE"
-    exit 1
-fi
-
-# Create backup
-cp "$STREAMLIT_INDEX" "${STREAMLIT_INDEX}.backup"
-
-# Use awk to inject after <head> tag
-awk -v inject_file="$INJECT_FILE" '
-/<head>/ {
-    print
-    while ((getline line < inject_file) > 0) {
-        print line
-    }
-    close(inject_file)
-    next
-}
-{ print }
-' "${STREAMLIT_INDEX}.backup" > "$STREAMLIT_INDEX"
-
-echo "[PWA] PWA meta tags successfully injected!"
-echo "[PWA] Backup saved as: ${STREAMLIT_INDEX}.backup"

pwa-head-inject.html

@@ -1,8 +0,0 @@
-<!-- PWA (Progressive Web App) Meta Tags -->
-<link rel="manifest" href="/app/static/manifest.json">
-<meta name="theme-color" content="#165ba8">
-<meta name="apple-mobile-web-app-capable" content="yes">
-<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
-<meta name="apple-mobile-web-app-title" content="BattleWords">
-<link rel="apple-touch-icon" href="/app/static/icon-192.png">
-<meta name="mobile-web-app-capable" content="yes">

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "battlewords"
 version = "0.2.37"
-description = "BattleWords vocabulary game with game sharing via shortened game_id URL referencing server-side JSON settings"
+description = "BattleWords vocabulary game (basic branch)"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"
 dependencies = [

specs/basic.mdx

@@ -90,21 +90,14 @@ The basic branch uses:
 - `component.html` is allowed for UI transitions/effects (spinners, scroll-to-anchor, overlays).
 - `component.html` must not be used for audio mounting in the basic branch.
 
-## Possible features to remove
-
-The following features are currently included, but may be considered for removal in an even more minimal version:
-- Challenge mode / Share Links / Remote Storage (HF)
-- PWA support (service worker, manifest, installability)
-
-
 ## Implementation Checklist
 
 - App starts with no errors.
 - New Game transition remains smooth (uses `CustomSpinner`).
 - Core gameplay works end-to-end (reveal, guess, scoring, radar, game over).
 - Game Over / Congratulations popup behaves correctly and remains smooth.
-- Challenge mode works via `?game_id=...` (load, play, submit/share).
-- PWA support remains functional (service worker/manifest still injected/served).
+- Challenge mode / share links / remote storage are removed.
+- PWA support is removed.
 - No audio playback occurs (no background music, no sound effects).
 - No AI/HF-model-backed word list generation occurs (local wordlists only).
 - No settings/leaderboard pages are reachable (`?page=settings` / `?page=leaderboard` disabled).

specs/history.mdx

@@ -1,25 +0,0 @@
-# Battlewords: History
-
-## Foundation
-- Invented in the early 1980s as "Word Battle," a paper-and-pencil grid game inspired by Battleship.
-- Used in reading classes for international students at San Diego State University.
-- In 1992, developed for submission to game agents; accepted by Technical Game Services (TGS).
-
-## Rename & Presentation
-- Renamed "Battlewords" in 1993.
-- Presented to Milton-Bradley at the New York trade show, but only as a videotaped paper prototype.
-- MB declined due to another European word game in development.
-
-## Sabotage & Similar Games
-- Turkish students reported a similar game, "The Admiral Sank," in Turkey.
-- Suspicions arose that students adapted and sold the idea, which became "Battle Words" (two words) in Europe, licensed to Hasbro International.
-- MB ultimately rejected the original Battlewords after seeing the European version.
-
-## Reboot & Digital Version
-- The European "Battle Words" faded into obscurity.
-- The original creator retained prototypes and correspondence.
-- Later collaborated with a Turkish programmer to create a Flash version of Battlewords for the website.
-- Plans to further develop the game.
-
-## Copyright
-BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.

specs/requirements.mdx

@@ -1,316 +1,99 @@
-# Battlewords: Implementation Requirements
+# Battlewords: Implementation Requirements
 
-**Current Version:** 0.2.37
-**Last Updated:** 2026-02-10
+**Current Version:** 0.2.37 BASIC
+**Branch:** `basic`
+**Last Updated:** 2026-02-11
 
-## Recent Changes (v0.2.37)
-See `README.md` for the canonical release notes: [Recent Changes](README.md#recent-changes)
+This document captures the implementation requirements for the **basic** branch only (single-player, default settings, one play experience).
 
-This document breaks down the tasks to build Battlewords using the game rules described in `specs.md`. It is organized in phases: a minimal Proof of Concept (POC), a Beta Version (0.5.0), and a Full Version (1.0.0).
+---
 
-Assumptions
-- Tech stack: Python 3.10+, Streamlit for UI, matplotlib for radar, numpy for tick helpers, Pillow for animated GIFs.
-- Single-player, local state stored in Streamlit session state for POC.
-- Grid is always 12x12 with exactly six words: two 4-letter, two 5-letter, two 6-letter words; horizontal/vertical only; no shared letters or overlaps in POC; shared-letter overlaps allowed in Beta; no overlaps in Full.
+## Assumptions
+- Tech stack: Python 3.10+, Streamlit (UI), matplotlib (radar), numpy (tick helpers), Pillow (animated GIFs).
+- Single-player only.
+- State is local and stored in Streamlit session state.
+- Grid is always 12×12 with exactly six words: two 4-letter, two 5-letter, two 6-letter words.
+- Words placed horizontal/vertical only.
 - Entry point is `app.py`.
 
-Streamlit key components (API usage plan)
-- State & caching
-  - `st.session_state` for `puzzle`, `grid_size`, `revealed`, `guessed`, `score`, `last_action`, `can_guess`.
-  - `st.session_state.points_by_word` for per-word score breakdown.
-  - `st.session_state.letter_map` derived from puzzle.
-  - `st.session_state.selected_wordlist` for sidebar picker.
-  - `st.session_state.radar_gif_path` for session-persistent radar animation.
-  - `st.session_state.show_incorrect_guesses` toggle.
-  - `st.session_state.show_challenge_share_links` toggle (v0.2.27, default OFF) to control visibility of challenge share links in the header and Game Over dialog.
+## Streamlit Key Components
 
-- Layout & structure
-  - `st.title`, `st.subheader`, `st.markdown` for headers/instructions.
-  - `st.columns(12)` to render the 12×12 grid; `st.container` for grouping; `st.sidebar` for secondary controls/help.
-  - `st.expander` for inline help/intel tips.
-  - Query-param routing via `st.query_params` using `?page=play|settings|leaderboard`.
-  - Footer navigation via `render_footer(current_page=...)`.
-- Widgets (interaction)
-  - `st.button` for each grid cell (144 total) with unique `key` to handle reveals.
-  - `st.form` + `st.text_input` + `st.form_submit_button("OK")` for controlled word guessing (disabled until guessing is allowed).
-  - `st.button("New Game")` to reset state; sidebar `selectbox` for wordlist selection and `Sort Wordlist` button (length+alpha).
-  - `st.metric` to show score.
-- Visualization
-  - Animated radar using matplotlib `FuncAnimation` + `PillowWriter` saved to GIF.
-  - Scope overlay image generated once and reused; metallic gradient background.
-  - Radar plot uses inverted Y so (0,0) is top-left.
-- Control flow
-  - App reruns on interaction; uses `st.rerun()` after state changes (reveal, guess); `st.stop()` after game over summary to freeze UI.
+### State & caching
+- `st.session_state` holds: `puzzle`, `grid_size`, `revealed`, `guessed`, `score`, `last_action`, `can_guess`, `points_by_word`, `letter_map`.
+- Word list loading uses `st.cache_data` where appropriate.
+- Radar rendering caches per-session artifacts (e.g., `radar_gif_path`).
 
-Folder Structure
-- `app.py` – Streamlit entry point
-- `battlewords/` – Python package
-  - `__init__.py`
-  - `models.py` – data models and types
-  - `word_loader.py` – load/validate/cached word lists (uses `battlewords/words/wordlist.txt` with fallback)
-  - `generator.py` – word placement; imports from `word_loader`; avoids duplicate words
-  - `logic.py` – game mechanics (reveal, guess, scoring, tiers)
-  - `ui.py` – Streamlit UI composition; animated radar; immediate rerender on reveal/guess via `st.rerun()`; inverted radar Y
-  - `settings_page.py` – Settings page renderer (used by `ui.py` via `?page=settings`)
-  - `ui_helpers.py` – Shared UI helpers (styles, footer navigation, PWA helpers)
-  - `words/wordlist.txt` – candidate words
-- `specs/` – documentation (this file and `specs.md`)
-- `tests/` – unit tests
+### Layout & structure
+- The app renders a single play experience.
+- No sidebar.
+- No footer navigation.
+- No query-param routing to non-game pages.
+
+### Widgets
+- Grid cell actions use `st.button` with unique keys.
+- Guessing uses `st.form` with `st.text_input` and `st.form_submit_button`.
+- A New Game action restarts gameplay.
 
-Phase 1: Proof of Concept (0.1.0)
-Goal: A playable, single-session game demonstrating core rules, scoring, and radar without persistence or advanced UX.
+### Visualization
+- Radar visualization uses matplotlib and renders as an animated GIF.
+- Radar plot uses inverted Y so (0,0) is top-left.
 
-1) Data Models
-- Define `Coord(x:int, y:int)`.
-- Define `Word(text:str, start:Coord, direction:str{"H","V"}, cells:list[Coord])`.
-- Define `Puzzle(words:list[Word], radar:list[Coord])` – radar holds last-letter coordinates.
-- Define `GameState(grid_size:int=12, puzzle:Puzzle, revealed:set[Coord], guessed:set[str], score:int, last_action:str, can_guess:bool)`.
+### UI transitions
+- `CustomSpinner` is used for initial load, New Game transition, and Game Over/overlay transitions.
+- `components.html` usage is allowed for UI transitions/effects.
 
-Acceptance: Types exist and are consumed by generator/logic; simple constructors and validators.
+---
 
-2) Word List
-- Add an English word list filtered to alphabetic uppercase, lengths in {4,5,6}.
-- Ensure words contain no special characters; maintain reasonable difficulty.
-- Streamlit: `st.cache_data` to memoize loading/filtering.
-- Loader is centralized in `word_loader.py` and used by generator and UI.
+## Core Requirements
 
-Acceptance: Loading function returns lists by length with >= 25 words per length or fallback minimal lists.
+### Word list
+- Word lists must be loaded from local files in `battlewords/words/`.
+- No AI generation and no model-backed wordlist fetching.
 
-3) Puzzle Generation (Placement)
+### Puzzle generation
 - Randomly place 2×4, 2×5, 2×6 letter words on a 12×12 grid.
-- Constraints (POC):
-  - Horizontal (left→right) or Vertical (top→down) only.
-  - No overlapping letters between different words (cells must be unique).
+- No overlapping letters between different words.
 - Compute radar pulses as the last cell of each word.
-- Retry strategy with max attempts; raise a controlled error if generation fails.
 
-Acceptance: Generator returns a valid `Puzzle` passing validation checks (no collisions, in-bounds, correct counts, no duplicates).
-
-4) Game Mechanics
+### Game mechanics
 - Reveal:
-  - Click a covered cell to reveal; if the cell is part of a word, show the letter; else mark empty (CSS class `empty`).
-  - After a reveal action, set `can_guess=True`.
+  - Clicking a covered cell reveals a letter (if in a word) or empty.
+  - After a reveal, set `can_guess=True`.
 - Guess:
-  - Accept a guess only if `can_guess` is True and input length ∈ {4,5,6}.
-  - Match guess case-insensitively against unguessed words in puzzle.
-  - If correct: add base points = word length; bonus points = count of unrevealed cells in that word at guess time; mark all cells of the word as revealed; add to `guessed`.
-  - If incorrect: no points awarded.
-  - After any guess, set `can_guess=False` and require another reveal before next guess.
-  - Exception: in default mode a correct guess allows chaining (`can_guess=True`); other modes may disable chaining.
-  - Streamlit: `with st.form("guess"):` + `st.text_input("Your guess")` + `st.form_submit_button("OK", disabled=not can_guess)`; after guess, call `st.rerun()`.
-- End of game when all 6 words are guessed or all word letters are revealed; display summary and tier, then `st.stop()`.
-
-Acceptance: Unit tests cover scoring, guess gating, and reveal behavior.
-
-5) UI (Streamlit)
-- Layout:
-  - Title and brief instructions via `st.title`, `st.subheader`, `st.markdown`.
-  - Left: 12×12 grid using `st.columns(12)`.
-  - Right: Animated radar, Correct/Try Again indicator, guess form, and score panel.
-  - Navigation: Footer links and query-param routing (`?page=...`).
-  - Settings: Dedicated settings page (`?page=settings`) rendered by `render_settings_page()`.
-- Visuals:
-  - Covered vs revealed styles; revealed empty cells use CSS class `empty`.
-  - Completed word cells styled with `bw-cell-complete`; cell tooltips show coordinates.
-  - Score panel shows a compact total; timer display is removed.
-
-Acceptance: Users can play end-to-end; radar shows exactly 6 pulses; reveal and guess update via rerun; completed words are visually distinct.
-
-6) Scoring Tiers
-- After game ends, compute tier:
-  - Good: 34–37
-  - Great: 38–41
-  - Fantastic: 42+
-
-7) Basic Tests
-- Placement validity (bounds, overlap, counts, no duplicate words).
-- Scoring logic and bonus calculation.
-- Guess gating (reveal required except chaining after correct guess when enabled).
-
-Current Deltas (0.1.3 → 0.1.10)
-- 0.1.3
-  - Sidebar wordlist select; sorting persists length-then-alpha ordering; auto new-game after 5s notice.
-  - Score panel improvements; per-word points; final score styling.
-- 0.1.4
-  - Animated radar GIF with metallic gradient and scope overlay; session reuse via `radar_gif_path`.
-  - Mobile layout improvements; tighter grid spacing and horizontal scroll per row.
-- 0.1.5
-  - Hit/Miss indicator derived from `last_action`.
-  - Completed word cells render as non-buttons with tooltips.
-  - Helper functions for scope image and stable letter map rebuild.
-- 0.1.10
-  - Game Mode selector (`standard`, `too easy`); chaining allowed only in `standard`.
-  - Guess feedback indicator switched to Correct/Try Again.
-  - Version footer shows commit/Python/Streamlit; ocean background effect.
-  - Word list default/persistence fixes and sort action persists after delay.
-- 0.2.24
-  - compress height
-  - change incorrect guess tooltip location
-  - update final screen layout
-  - add word difficulty formula
-  - update documentation
-- 0.2.28
-  - Add Progressive Web App (PWA) support with `service worker` and `manifest.json`
-  - Add INSTALL_GUIDE.md for PWA install instructions
-  - No gameplay logic changes
-
-Known Issues / TODO
-- Word list selection bug: improper list fetched/propagated in some runs.
-  - Verify `get_wordlist_files()` returns correct filenames and `selected_wordlist` persists across `_new_game()`.
-  - Ensure `load_word_list(selected_wordlist)` loads the chosen file and matches `generate_puzzle(words_by_len=...)` expected shape.
-  - Add tests for selection, sorting, and fallback behavior.
-
-Phase 1.5: Storage and Sharing (0.3.0) - NEW  
-Goal: Add persistent storage, high scores, and game sharing capabilities.
-
-A) Storage Module  
-- Create `battlewords/storage.py` with:
-  - `GameStorage` class for saving/loading game results and high scores
-  - `GameResult` and `HighScoreEntry` dataclasses
-  - JSON-based local storage in `~/.battlewords/data/`
-- Update `models.py` to include `game_id` in Puzzle (based on word list)
-- Update `generator.py` to:
-  - Generate game_id from sorted word list
-  - Accept optional `target_words` parameter for replay
-- Integrate storage into game flow:
-  - Save result on game completion
-  - Display high scores in sidebar
-Acceptance:
-- Game results saved to local JSON files
-- High scores correctly filtered and sorted
-- Game IDs generated deterministically
-
-B) Game Sharing  
-- Parse `game_id` from query params (`?game_id=ABC123`)
-- Generate puzzle from game_id (same words, different positions)
-- "Share Challenge" button creates shareable URL
-- Display game_id in UI to show shared challenges
-Acceptance:
-- URL with game_id loads same word set
-- Share button generates correct URL
-- Game ID visible to players
-
-C) High Score Display  
-- Sidebar expander for high scores
-- Filter by: All-time, Current Wordlist, Current Mode
-- Top 10 entries with: Rank, Player, Score, Tier, Time
-- Player name input (optional, defaults to "Anonymous")
-Acceptance:
-- High scores display correctly
-- Filters work as expected
-- Player names saved with results
-
-D) Tests  
-- Unit tests for storage operations
-- Test game ID generation consistency
-- Test save/load result flow
-- Test high score filtering and ranking
-
-Milestones and Estimates (High-level)
-- Phase 1 (POC): 2–4 days ✅ COMPLETE
-- Phase 1.5 (Local Storage & Sharing - planned): 2–3 days ⏳ PENDING (deferred to v0.3.0)
-- Phase 1.6 (Remote Storage & Challenge Mode): 3–4 days ✅ COMPLETE (v0.2.20-0.2.27)
-- Phase 1.7 (Local Player History): 2–3 days ⏳ IN PROGRESS (v0.3.0)
-- Beta (0.5.0): 3–5 days (overlaps, responsive UI, keyboard, deterministic seed)
-- Phase 2 (Full): 1–2 weeks depending on features selected
-
-Definitions of Done (per task)
-- Code merged with tests and docs updated.
-- No regressions in existing tests; coverage maintained or improved for core logic.
-- Manual playthrough validates rules: reveal/guess gating, scoring, radar pulses, end state and tiers.
-
-## v0.2.20 Update: Game Sharing with Shortened game_id URL
-
-### Game Sharing Feature
-- On game completion, save a JSON file to the storage server named by a unique `uid`.
-- The JSON file contains: word_list, score, time, game_mode, grid_size, and puzzle options.
-- Generate a shortened URL for this file; use it as the `game_id` in the shareable link.
-- When a user loads a game with a `game_id` query string, fetch the JSON file and apply all settings for the session.
-
-### Implementation Notes
-- The game_id is a shortened URL referencing the JSON file.
-- The app applies all settings from the file for a true replay.
-- No direct encoding of game data in the query string; only the reference is shared.
-
-## Phase 1.6: Remote Storage & Challenge Mode (v0.2.20-0.2.27) ✅ COMPLETE
-
-### Goal
-Persist per-game settings and leaderboards on a storage server (Hugging Face Hub repo) with shortened URLs for challenge sharing.
-
-### A) Storage Server Integration ✅
-- Imported modules from OpenBadge `modules/storage.py`:
-  - `upload_files_to_repo(...)` to write JSON to `HF_REPO_ID`
-  - `gen_full_url(...)` for shortener lookups/creation backed by `shortener.json`
-- Created `battlewords/game_storage.py` wrapper with functions:
-  - `save_game_to_hf()` - Save challenge and get short URL
-  - `load_game_from_sid()` - Load challenge from short ID
-  - `add_user_result_to_game()` - Append user result to existing challenge
-  - `get_shareable_url()` - Generate shareable URLs
-- Repository structure in HF dataset:
-  - `shortener.json` - Short URL mappings
-  - `games/{uid}/settings.json` - Per-game challenge data with users array
-- Required env vars (.env): `HF_API_TOKEN` (or `HF_TOKEN`), `HF_REPO_ID`, `SPACE_NAME`
-
-### B) Sharing Link (game_id) ✅
-- Shortened URL flow: `gen_full_url(full_url=...)` returns short id (sid)
-- Shareable link format: `https://<SPACE_NAME>/?game_id=<sid>`
-- On app load with `game_id`: fetch JSON, apply settings, show Challenge Mode banner
-
-### C) Challenge Mode Features ✅
-- Multi-user leaderboards with score, time, and difficulty tracking
-- Results sorted by: highest score → fastest time → highest difficulty
-- Challenge Mode UI banner showing top 5 players
-- Submit result to existing challenge or create new challenge
-- Word list difficulty calculation and display
-- "Show Challenge Share Links" toggle (default OFF) for URL visibility control
-- Share links are only rendered in the Challenge Mode banner and Game Over flow when the toggle is enabled.
-- Each player gets different random words from the same wordlist source
-
-### D) Dependencies ✅
-- Added `huggingface_hub` and `python-dotenv` to requirements
-- Module imports in `ui.py:30`
-
-### E) Acceptance Criteria ✅
-- ✅ Completed game produces working share link with `game_id` sid
-- ✅ Visiting link reconstructs challenge with leaderboard
-- ✅ Multiple users can submit results to same challenge
-- ✅ Leaderboard displays and sorts correctly
-- ✅ Documentation updated with env vars and flows
-- ✅ App works without HF credentials (Challenge Mode features disabled gracefully)
-
-### F) Implementation Files
-- `battlewords/game_storage.py` - HF storage wrapper (v0.1.0)
-- `battlewords/modules/storage.py` - Generic HF storage (v0.1.5)
-- `battlewords/ui.py` - Challenge Mode UI integration (lines 508-601, 1588-1701)
-- `battlewords/generator.py` - Support for target_words parameter
-
-## Phase 1.7: Local Player History (v0.3.0) ⏳ IN PROGRESS
-
-### Goal
-Add local persistent storage for individual player game results and personal high scores (offline-capable, privacy-first).
-
-### A) Local Storage Module
-- Create `battlewords/local_storage.py` with:
-  - `GameResult` and `HighScoreEntry` dataclasses
-  - JSON-based storage in `~/.battlewords/data/`
-  - Functions: `save_game_result()`, `load_high_scores()`, `get_player_stats()`
-  - Storage location: `~/.battlewords/data/` (game_results.json, highscores.json)
-
-### B) High Score Display
-- Sidebar expander for personal high scores
-- Filter by: All-time, Current Wordlist, Current Mode
-- Top 10 entries with: Rank, Player, Score, Tier, Time
-- Player name input (optional, defaults to "Anonymous")
-
-### C) Player Statistics
-- Games played, average score, best score
-- Fastest completion time
-- Per-player history tracking
-
-### D) Acceptance Criteria
-- Local JSON files created and updated on game completion
-- High scores display correctly in sidebar
-- Filters work as expected
-- Player names saved with results
-- No cloud dependency required
-- Easy data deletion (remove ~/.battlewords/data/)
+  - Only allowed if `can_guess=True`.
+  - Correct guess awards base points (= word length) plus bonus points (= unrevealed letters at guess time).
+  - On correct guess: mark all word cells as revealed and add word to `guessed`.
+  - On incorrect guess: no points.
+  - After any guess: set `can_guess=False`.
+  - Default behavior: chaining after a correct guess is allowed (no settings UI required).
+- Game over:
+  - Triggered when all six words are guessed or when all word letters are revealed.
+  - Shows a summary with score and tier.
+
+### Scoring tiers
+- Good: 34–37
+- Great: 38–41
+- Fantastic: 42–45
+- Legendary: 46+
+
+---
+
+## Folder Structure (Basic)
+- `app.py` – Streamlit entry point
+- `battlewords/`
+  - `models.py` – data models and types
+  - `word_loader.py` – load/validate/cached word lists
+  - `generator.py` – word placement
+  - `logic.py` – reveal/guess/scoring/tier rules
+  - `ui.py` – Streamlit UI composition
+  - `ui_helpers.py` – shared UI helpers (styles/transitions)
+  - `words/` – local word list files
+- `specs/` – documentation
+
+## Out of Scope (Basic)
+- Settings page
+- Leaderboards
+- Challenge mode / remote storage (removed)
+- PWA support (removed)
+- Audio
+- Tests

specs/specs.mdx

@@ -1,209 +1,75 @@
-# Battlewords Game Requirements (specs.md)
+# Battlewords Game Requirements
 
-**Current Version:** 0.2.37
-**Last Updated:** 2026-02-10
+**Current Version:** 0.2.37 BASIC
+**Branch:** `basic`
+**Last Updated:** 2026-02-11
 
 ## Overview
 Battlewords is inspired by the classic Battleship game, but uses words instead of ships. The objective is to discover hidden words on a grid, earning points for strategic guessing before all letters are revealed.
 
-## Upgrade Checklist
-The detailed Wrdler  BattleWords porting checklist is tracked in `specs/upgrade.mdx`.
-
-## Recent Changes (v0.2.37)
-See `README.md` for the canonical release notes: [Recent Changes](README.md#recent-changes)
-
 ---
 
 ## Game Board
-- 12 x 12 grid.
+- 12×12 grid.
 - Six hidden words:
   - Two four-letter words
   - Two five-letter words
   - Two six-letter words
 - Words are placed horizontally (left-right) or vertically (top-down), not diagonally.
-- Words may touch edges or corners but do not overlap unless a future mode allows shared letters.
+- Words may touch edges or corners but do not overlap.
 - Entry point is `app.py`.
-- **Supports Dockerfile-based deployment for Hugging Face Spaces and other container platforms.**
+- Supports Dockerfile-based deployment for container platforms.
 
-## Gameplay (Common)
+## Gameplay
 - 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.
-- Use radar pulses to locate word boundaries (first and last letters).
-- 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.
+- After any reveal, the app reruns (`st.rerun`) to show the change.
+- Radar pulses indicate the last letter of each hidden word.
+- After revealing a letter, players may guess a word via a text input.
+- Guess submission reruns the app 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.**
+- Correct guesses allow 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
+  - Bonus points for each hidden (unrevealed) letter at the time of guessing
 - Score tiers:
-  - Good: 34-37
-  - Great: 38-41
-  - Fantastic: 42-45
-  - Legendary: 46+ (perfect game)
-- **Game over is triggered by either all words being guessed or all word letters being revealed.**
-
-## POC (0.1.0) Rules
-- No overlaps: words do not overlap or share letters.
-- UI: basic grid, radar, and guess form.
-- No keyboard interaction requirement.
-- Seed is optional and not standardized.
-
-## Beta (0.5.0) Additions
-- Optional validation pass to avoid unintended adjacent partial words (content curation rule).
-- Cell rendering with consistent sizing and responsive layout (desktop/mobile).
-- Keyboard support for navigation and guessing (custom JS via `st.html` or a component).
-- Deterministic seed support to reproduce puzzles (e.g., daily seed derived from date).
-
-## Full (1.0.0) Rules
-- No overlaps: words do not overlap or share letters.   
-- Enhanced UX polish (animations, accessibility, themes).
-- Persistence, leaderboards, and additional modes as specified in requirements.
-- Deterministic daily mode and practice mode supported.
-
-## New Features (v0.3.0)
-- **Game ID Sharing:** Each puzzle generates a deterministic game ID based on the word list. Players can share URLs with `?game_id=ABC123` to challenge others with the same words.
-- **Persistent Storage:** Game results and high scores are saved locally in `~/.battlewords/data/`.
-- **High Scores:** Top scores are tracked and displayed in the sidebar, filterable by wordlist and game mode.
-- **Player Name:** Optional player name is saved with results.
-
-## New Features (v0.2.28)
-- **PWA Support:** 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.
-
-## New Features (v0.2.24)
-- **UI Improvements:** More compact layout, improved tooltip for incorrect guesses, and updated final score screen.
-- **Word Difficulty:** Added a word difficulty formula and display for each game/challenge, visible in the final score and leaderboard.
-- **Challenge Mode:** Enhanced leaderboard with difficulty display, improved result submission, and clearer challenge sharing.
-- **Documentation:** Updated to reflect new features and UI changes.
-
-## Storage
-- Game results and high scores are stored in JSON files for privacy and offline access.
-- Game ID is generated from the sorted word list for replay/sharing.
+  - Good: 34–37
+  - Great: 38–41
+  - Fantastic: 42–45
+  - Legendary: 46+
 
 ## UI Elements
-- 12x12 grid
-- Radar screen (shows last letter locations); y-axis inverted so (0,0) is top-left
-- Text box for word guesses
-- Score display (shows word, base points, bonus points, total score)
-- Guess status indicator (Correct/Try Again)
-- Game ID display and share button in game over dialog.
-- High score expander in sidebar.
-- Player name input in sidebar.
-- Checkbox: "Show Challenge Share Links" (v0.2.27, 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"
-
-## New Features (v0.2.27)
-- Added "Show Challenge Share Links" visibility toggle for Challenge Mode sharing UI
-- Purely a UI change; gameplay logic and storage behavior unchanged
-
-## Word List
-- External list at `battlewords/words/wordlist.txt`.
-- Loaded by `battlewords.word_loader.load_word_list()` with caching.
-- Filtered to uppercase A�Z, lengths in {4,5,6}; falls back if < 25 per length.
+- 12×12 clickable grid
+- Radar screen (GIF) showing last-letter pulse locations
+- Guess input form
+- Score panel (base + bonus breakdown)
+- Game over summary dialog (final score + tier)
+- New Game button
+- Custom loading spinner/overlay for transitions
+- No sidebar, no settings page, no leaderboards
+
+## Word Lists
+- Local word list files under `battlewords/words/`.
+- Loaded via `battlewords.word_loader.load_word_list()`.
+- Filtered to uppercase A–Z and lengths {4, 5, 6}.
 
 ## Generator
 - Centralized word loader.
 - No duplicate word texts are selected.
 
-## 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).
+## Deployment
+- No special configuration needed.
+- Local: `streamlit run app.py`
+- Docker: use the provided `Dockerfile`
 
-### 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/BattleWords    # 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/BattleWordsStorage`)
-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
+## Out of Scope (Basic)
+- Challenge mode / share links / remote storage (removed)
+- PWA support (removed)
+- Audio
+- Query-param routing to non-game pages
 
 ## Copyright
-BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.
-
-## v0.2.20: Remote Storage and Shortened game_id URL
-
-Game Sharing
-- Each puzzle can be shared via a link containing a `game_id` querystring (short id / sid)
-- `game_id` resolves to a settings JSON on the storage server (HF repo)
-- JSON fields:
-  - word_list (list of 6 uppercase words)
-  - score (int), time (int seconds) [metadata only]
-  - game_mode (e.g., classic, too easy)
-  - grid_size (e.g., 12)
-  - puzzle_options (e.g., { spacer, may_overlap })
-- On load with `game_id`, fetch and apply: word_list, game_mode, grid_size, puzzle_options
-
-High Scores
-- Repository maintains `highscores/highscores.json` for top scores
-- Local highscores remain supported for offline use
-
-UI/UX
-- Show the current `game_id` (sid) and a �Share Challenge� link
-- When loading with a `game_id`, indicate the puzzle is a shared challenge
-
-Security/Privacy
-- Only game configuration and scores are stored; no personal data is required
-- `game_id` is a short reference; full URL is stored in a repo JSON shortener index
-
-## Challenge Mode & Leaderboard
-
-- When loading a shared challenge via `game_id`, the leaderboard displays all user results for that challenge.
-- **Sorting:** The leaderboard is sorted by highest score (descending), then by fastest time (ascending).
-- **Difficulty:** Each result now displays a computed word list difficulty value.
-- Results are stored remotely in a Hugging Face dataset repo and updated via the app.
+Battlewords. All Rights Reserved.

specs/upgrade.mdx

@@ -1,136 +0,0 @@
-# Upgrade checklist: porting useful `wrdler` improvements into `battlewords`
-
-**Current Version:** 0.2.34
-**Last Updated:** 2025-01-20
-
-## Recent Changes (v0.2.34)
-See `README.md` for the canonical release notes: [Recent Changes](../README.md#recent-changes)
-
-## Context summary (for a fresh chat)
-
-- **Goal:** Bring over non-gameplay improvements from `wrdler` into `battlewords`—primarily **leaderboards**, **settings management**, **UI/navigation**, and **remote storage helpers**.
-- **Out of scope:** Anything that changes BattleWords core gameplay (grid rules, word placement logic, scoring mechanics, etc.).
-- **Key BattleWords file already in scope:** `battlewords/game_storage.py` (HF-backed challenge saving/loading, multi-user challenge results, and robust share URL generation).
-- **Important existing BattleWords capability:** `battlewords/game_storage.py:get_shareable_url()` supports embedded hosting via `iframe_host` query param, local dev URLs, and Space URLs.
-- **Wrdler sources used for comparison:** ( use MCP tool fss. relative file path is ../projects/wrdler/ )
-  - `d:/projects/wrdler/pyproject.toml` (project metadata)
-  - `d:/projects/wrdler/readme.md` (feature list; describes leaderboards/settings/navigation)
-  - `d:/projects/wrdler/specs/settings.md` (settings page + local settings persistence design)
-  - `d:/projects/wrdler/wrdler/ui.py` (query-param routing, footer nav, challenge UX, game-over submission flow)
-  - `d:/projects/wrdler/wrdler/version_info.py` (runtime diagnostics HTML snippet)
-  - `d:/projects/wrdler/wrdler/modules/*` (constants/settings loader, HF storage helpers, repo folder listing)
-- **BattleWords repo remotes (for reference):**
-  - Hugging Face Space: `https://huggingface.co/spaces/Surn/BattleWords`
-  - GitHub: `https://github.com/Oncorporation/BattleWords`
-- **Notable Wrdler improvements to port:**
-  - Dedicated Settings page using `?page=settings` + footer navigation.
-  - Local settings persistence (load latest settings on startup; save settings to local JSON files).
-  - Daily/weekly leaderboards stored in HF with folder-based discovery (no global `index.json`) + settings-based separation.
-  - Challenge mode UX polish (top-N preview, exit challenge mode, optional share-link display).
-  - Game-over dialog integrates submission + share link generation + qualification feedback.
-  - Runtime diagnostics footer: app version, git commit, python and streamlit versions.
-- **Implementation notes / constraints:**
-  - Prefer minimal changes; preserve existing behavior.
-  - Track work by checking items below when implemented.
-  - **Porting reminder:** `wrdler/version_info.py` is now `battlewords/modules/version_info.py` (BattleWords expects this kind of shared utility under `modules`).
-
-Scope: only non-gameplay changes (leaderboards, settings, UI/UX, storage/utilities). Ignore gameplay differences.
-
----
-
-## UI/UX Improvements (from Wrdler)
-
-- [x] Combine "Your Guess" and guess result into a single UI element, as in Wrdler.
-- [x] Shrink space in scoreboard for a more compact screen layout.
-- [x] Radar graphic size reduced to 240px to save processing and load time.
-- [x] Remove waves from background for cleaner look and better performance.
-
----
-
-## Settings system improvements
-
-- [x] Create a dedicated Settings page (route like `?page=settings`) instead of relying on a sidebar.
-- [x] Implement local settings persistence (load latest settings on startup, save current settings).
-- [ ] Add multi-profile settings management (create/update/rename/delete settings configurations) (optional).
-- [x] Centralize defaults/overrides via a single settings loader (defaults + `settings.json` + env overrides).
-
----
-
-## Navigation + routing
-
-- [x] Add footer navigation as primary nav (Play / Leaderboard / Settings) rather than sidebar links.
-- [x] Implement query-param routing (e.g., `?page=play|settings|today|daily|weekly|history`) for multi-page UI.
-- [ ] Ensure routing avoids unnecessary page reload loops and preserves UI state where possible.
-
----
-
-## Challenge sharing UX
-
-- [x] Standardize share URL generation using `get_shareable_url()` (avoid hard-coded Space URLs).
-- [x] Ensure embedded deployments work via `iframe_host` override (BattleWords already supports this).
-- [x] Add a “Show share links” toggle so share URLs aren’t always displayed.
-- [ ] Add an “Exit challenge mode” action that clears `game_id` and resets challenge session flags.
-
----
-
-## Challenge mode banner / presentation
-
-- [x] Add a Challenge Mode banner/expander that summarizes the challenge.
-- [x] Show “top N” (e.g., 5) results preview in the banner (sorted by score desc, time asc, difficulty desc).
-- [x] Display optional `word_list_difficulty` per user in the preview when present.
-
----
-
-## Game Changes
-
-- [x] faster loading
-- [x] remove timer
-- [x] remove settings panel entirely
-- [x] plain blue background (no waves)
-- [x] no empty guesses
-- [x] guess box rearranged to be more compact, circle around guess and result, no OK button
-- [x] New Game button moved to be stable (not flash)
-- [x] faster time for growing glow when word is complete
-- [x] smaller radar
-- [x] No share challenge on results page
-- [x] No leaderboard on results page
-- [x] No settings
-- [x] Change subheader text
-
-## Game-over flow improvements
-
-- [x] Integrate “submit score” + “generate share link” into the game-over dialog/popup.
-- [x] Display qualification/rank results after submission.
-- [ ] Provide links into leaderboard views using query params.
-
----
-
-## Daily/weekly leaderboards (port selectively)
-
-- [ ] Decide minimal leaderboard scope for BattleWords (start with Daily only, add Weekly later).
-- [ ] Use settings-based leaderboard separation (players compete only with identical settings).
-- [ ] Implement top-N display (e.g., 25) with deterministic sorting: score desc → time asc → difficulty desc.
-- [ ] Store leaderboards in HF using folder-based discovery (avoid a global `index.json`).
-- [ ] Track challenge submissions into daily/weekly leaderboards via `source_challenge_id`.
-- [ ] Provide leaderboard browsing UI (tabs like Today / Daily / Weekly / History).
-
----
-
-## Storage/utilities to unlock leaderboards
-
-- [x] Add HF repo folder listing helper (for folder-based discovery leaderboards).
-- [x] Add HF repo “list files in folder” helper.
-
----
-
-## Version + runtime diagnostics (supportability)
-
-- [x] Port `wrdler/version_info.py` into `battlewords/modules/version_info.py` (note: BattleWords needs it under `modules`).
-- [x] Add a footer snippet that shows app version + git commit + python + streamlit versions.
-
----
-
-## Dependency/workflow alignment (optional)
-
-- [x] Validate Streamlit version supports modern `st.query_params` API.
-- [ ] Consider aligning Python/Streamlit pins (as needed) to support routing/dialog APIs used by Wrdler.

static/manifest.json

@@ -1,27 +0,0 @@
-{
-  "name": "BattleWords",
-  "short_name": "BattleWords",
-  "description": "Vocabulary learning game inspired by Battleship mechanics. Discover hidden words on a 12x12 grid and earn points for strategic guessing.",
-  "start_url": "/",
-  "scope": "/",
-  "display": "standalone",
-  "orientation": "portrait",
-  "background_color": "#0b2a4a",
-  "theme_color": "#165ba8",
-  "icons": [
-    {
-      "src": "/app/static/icon-192.png",
-      "sizes": "192x192",
-      "type": "image/png",
-      "purpose": "any maskable"
-    },
-    {
-      "src": "/app/static/icon-512.png",
-      "sizes": "512x512",
-      "type": "image/png",
-      "purpose": "any maskable"
-    }
-  ],
-  "categories": ["games", "education"],
-  "screenshots": []
-}

static/service-worker.js

@@ -1,99 +0,0 @@
-/**
- * BattleWords Service Worker
- * Enables PWA functionality: offline caching, install prompt, etc.
- *
- * Security Note: This file contains no secrets or sensitive data.
- * It only caches public assets for offline access.
- */
-
-const CACHE_NAME = 'battlewords-v0.2.29';
-const RUNTIME_CACHE = 'battlewords-runtime';
-
-// Assets to cache on install (minimal for faster install)
-const PRECACHE_URLS = [
-  '/',
-  '/app/static/manifest.json',
-  '/app/static/icon-192.png',
-  '/app/static/icon-512.png'
-];
-
-// Install event - cache essential files
-self.addEventListener('install', event => {
-  console.log('[ServiceWorker] Installing...');
-  event.waitUntil(
-    caches.open(CACHE_NAME)
-      .then(cache => {
-        console.log('[ServiceWorker] Precaching app shell');
-        return cache.addAll(PRECACHE_URLS);
-      })
-      .then(() => self.skipWaiting()) // Activate immediately
-  );
-});
-
-// Activate event - clean up old caches
-self.addEventListener('activate', event => {
-  console.log('[ServiceWorker] Activating...');
-  event.waitUntil(
-    caches.keys().then(cacheNames => {
-      return Promise.all(
-        cacheNames.map(cacheName => {
-          if (cacheName !== CACHE_NAME && cacheName !== RUNTIME_CACHE) {
-            console.log('[ServiceWorker] Deleting old cache:', cacheName);
-            return caches.delete(cacheName);
-          }
-        })
-      );
-    }).then(() => self.clients.claim()) // Take control immediately
-  );
-});
-
-// Fetch event - network first, fall back to cache
-self.addEventListener('fetch', event => {
-  // Skip non-GET requests
-  if (event.request.method !== 'GET') {
-    return;
-  }
-
-  // Skip chrome-extension and other non-http requests
-  if (!event.request.url.startsWith('http')) {
-    return;
-  }
-
-  event.respondWith(
-    caches.open(RUNTIME_CACHE).then(cache => {
-      return fetch(event.request)
-        .then(response => {
-          // Cache successful responses for future offline access
-          if (response.status === 200) {
-            cache.put(event.request, response.clone());
-          }
-          return response;
-        })
-        .catch(() => {
-          // Network failed, try cache
-          return caches.match(event.request).then(cachedResponse => {
-            if (cachedResponse) {
-              console.log('[ServiceWorker] Serving from cache:', event.request.url);
-              return cachedResponse;
-            }
-
-            // No cache available, return offline page or error
-            return new Response('Offline - Please check your connection', {
-              status: 503,
-              statusText: 'Service Unavailable',
-              headers: new Headers({
-                'Content-Type': 'text/plain'
-              })
-            });
-          });
-        });
-    })
-  );
-});
-
-// Message event - handle commands from the app
-self.addEventListener('message', event => {
-  if (event.data.action === 'skipWaiting') {
-    self.skipWaiting();
-  }
-});