0.2.19

- Fix music and sound effect volume issues
- Update documentation for proposed new features

.gitignore

@@ -490,3 +490,4 @@ secrets.*
 /battlewords/__pycache__/__init__.cpython-311.pyc
 /package.json
 /package-lock.json
+/.claude

README.md

@@ -112,6 +112,33 @@ docker run -p8501:8501 battlewords
  - High Scores: local leaderboard tracking top scores by wordlist and game mode.
  - Persistent Storage: all game results saved locally for personal statistics without accounts.
 
+-0.2.20 (development)
+ - 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`
+
+### 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 will be added in a later PR to avoid confusion with generic modules
+
+-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)

battlewords/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "0.2.18"
+__version__ = "0.2.19"
 __all__ = ["models", "generator", "logic", "ui"]

battlewords/storage.py

@@ -1,4 +1,4 @@
-// file: battlewords/storage.py
+# file: battlewords/storage.py
 """
 Storage module for BattleWords game.
 

claude.md

@@ -309,3 +309,96 @@ pytest tests/
 - 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+.
+
+## v0.2.20: Remote Storage game_id via Shortened URL
+
+Overview
+- Use a storage server (Hugging Face Hub repo) to persist:
+  - Per-game settings JSON (word_list, score, time, game_mode, grid_size, puzzle options)
+  - High scores JSON (top scores)
+- Each completed game writes JSON to repo under a unique `uid` folder.
+- A shortened URL (sid) referencing the settings JSON is generated and used as `game_id` in the query string.
+- On load, if `?game_id=<sid>` exists, resolve sid to the full JSON URL, fetch it, and apply settings for the session.
+
+Modules to leverage (from OpenBadge/modules)
+- `modules/storage.py`
+  - `upload_files_to_repo(files, repo_id, folder_name, repo_type="dataset")`
+  - `gen_full_url(short_url=None, full_url=None, repo_id=None, json_file="shortener.json")`
+- `modules/constants.py` (env + defaults)
+  - Uses HF token from env (expects `HF_TOKEN`, we will also document `HF_API_TOKEN`)
+  - `HF_REPO_ID`, `SPACE_NAME`, `SHORTENER_JSON_FILE`
+- `modules/file_utils.py` (helpers)
+
+Environment variables (.env)
+- HF_API_TOKEN or HF_TOKEN: Hugging Face access token (Bearer)
+- CRYPTO_PK: optional, reserved for future signing
+- HF_REPO_ID: target repo, e.g., Surn/Storage
+- SPACE_NAME: e.g., Surn/BattleWords
+
+Repository structure (dataset repo)
+- shortener.json                # sid -> full URL mapping
+- games/{uid}/settings.json     # per-game settings payload (primary)
+- games/{uid}/result.json       # finalized game result (optional)
+- highscores/highscores.json    # global/top scores JSON
+
+Game settings JSON (example)
+{
+  "uid": "20250101T120001Z-ABC123",
+  "word_list": ["APPLE","TRAIN","..."],
+  "score": 40,
+  "time": 173,
+  "game_mode": "classic",
+  "grid_size": 12,
+  "puzzle_options": { "spacer": 1, "may_overlap": false }
+}
+
+Flow
+1) On game completion
+   - Build unique `uid` (timestamp + random suffix).
+   - Write settings.json (and optional result.json) to games/{uid}/
+   - Create full URL to settings.json, call `gen_full_url(full_url=...)` to obtain `sid`
+   - Share link: https://<space>/?game_id=<sid>
+2) On load with `?game_id=<sid>`
+   - Call `gen_full_url(short_url=sid)` to get full URL
+   - Fetch settings.json, apply session: word_list, game_mode, grid_size, puzzle options; ignore score/time for gameplay
+3) Highscores
+   - Maintain highscores/highscores.json in repo; append/update with best entries
+
+Security/Privacy
+- Only game configuration and scores are stored; no PII required
+- sid is a reference; shortener.json can be in the same repo
+- Consider private repo for write access; dataset can be public for read
+
+Notes
+- We will keep `battlewords/storage.py` as local-only storage (JSON on disk) and introduce a new integration wrapper in a later PR (e.g., `battlewords/hf_storage.py`) to avoid confusion with the generic modules. If needed, rename `battlewords/storage.py` to `local_storage.py` in a future pass.
+- Add dependencies: `huggingface_hub`, `python-dotenv`
+
+## Documentation Structure
+
+This file (CLAUDE.md) serves as a **living context document** for AI-assisted development. It complements the formal specification documents:
+
+- **[specs/specs.md](specs/specs.md)** - Game rules, requirements, and feature specifications
+- **[specs/requirements.md](specs/requirements.md)** - Implementation phases, acceptance criteria, and technical tasks
+- **[README.md](README.md)** - User-facing documentation, installation guide, and changelog
+
+**When to use each:**
+- **specs.md** - Understanding game rules, scoring, and player experience
+- **requirements.md** - Planning implementation work, tracking phases, and defining done criteria
+- **CLAUDE.md** - Quick reference for codebase structure, recent changes, and development context
+- **README.md** - Public-facing information, setup instructions, and feature announcements
+
+**Synchronization:**
+Changes to game mechanics should update specs.md → requirements.md → CLAUDE.md → README.md in that order

pyproject.toml

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

requirements.txt

@@ -7,4 +7,6 @@ Pillow
 pytest
 flake8
 mypy
-requests
+requests
+huggingface_hub
+python-dotenv

specs/requirements.md

@@ -192,3 +192,58 @@ 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 & Sharing (0.2.20)
+
+Goal
+- Persist per-game settings and highscores on a storage server (Hugging Face Hub repo).
+- Use a shortened `game_id` (sid) that resolves to settings.json for replay/sharing.
+
+A) Storage Server Integration
+- Use 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`
+- Create per-game folder `games/{uid}/` and write:
+  - `settings.json` with: word_list, score, time, game_mode, grid_size, puzzle options
+  - (optional) `result.json` with additional details for analytics
+- Maintain `highscores/highscores.json` for top scores
+- Env vars (.env): `HF_API_TOKEN` (or `HF_TOKEN`), `CRYPTO_PK`, `HF_REPO_ID`, `SPACE_NAME`
+
+B) Sharing Link (game_id)
+- After upload of `settings.json`, call `gen_full_url(full_url=...)` to obtain a short id (sid)
+- Shareable link: `https://<SPACE_NAME>/?game_id=<sid>`
+- On app load with `game_id`, call `gen_full_url(short_url=sid)`, fetch JSON, apply settings
+
+C) App Behavior
+- When `game_id` exists:
+  - Apply `game_mode`, `grid_size`, `puzzle_options` directly
+  - Load `word_list` as the target set; positions remain randomized unless later extended
+  - Ignore `score`/`time` for gameplay; those are metadata only
+- Continue to support local JSON storage for users without HF credentials
+
+D) Dependencies
+- Add `huggingface_hub` and `python-dotenv` to requirements
+- Ensure `requests` remains present for HTTP fetch fallback if needed
+
+E) Acceptance
+- A completed game produces a working share link with `game_id` sid
+- Visiting the link reconstructs the session settings from storage server JSON
+- Highscores JSON updates in the repo
+- Documentation updated with env vars, repo structure, and flows
+
+F) Implementation Notes
+- Do not replace `battlewords/storage.py` now; introduce a separate integration wrapper (e.g., `battlewords/hf_storage.py`) in the next PR
+- Consider a private repo for write access; shortener JSON and settings JSONs can be public read

specs/specs.md

@@ -88,3 +88,28 @@ Battlewords is inspired by the classic Battleship game, but uses words instead o
 
 ## 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