0.2.17 (claude code)

- documentation updates and corrections
- updated CLAUDE.md with accurate feature status and project structure
- clarified v0.3.0 planned features vs current implementation

README.md

@@ -93,6 +93,7 @@ docker run -p 8501:8501 battlewords
   - `generator.py` – word placement logic
   - `logic.py` – game mechanics (reveal, guess, scoring)
   - `ui.py` – Streamlit UI composition
+  - `storage.py` – **NEW**: persistent storage and high scores
   - `words/wordlist.txt` – candidate words
 - `specs/` – documentation (`specs.md`, `requirements.md`)
 - `tests/` – unit tests
@@ -106,6 +107,11 @@ docker run -p 8501:8501 battlewords
 
 ## Changelog
 
+-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)
@@ -358,3 +364,50 @@ For any issues or enhancements, please refer to the project documentation or con
 
 Happy gaming and sound designing!
 
+## What's New in v0.3.0
+
+### Game Sharing 🔗
+- Each game gets a unique ID based on the word combination
+- Share challenges with friends via URL (`?game_id=ABC123`)
+- Friends get the same words but different positions
+- Compare scores on the same puzzle!
+
+### High Scores 🏆
+- Local high score tracking (stored in `~/.battlewords/data/`)
+- Filter high scores by wordlist and game mode
+- Top 10 leaderboard display
+- Player names supported (optional)
+
+### Persistent Storage 💾
+- All game results automatically saved locally
+- View your personal statistics
+- No account needed - everything stored on your device
+
+## Folder Structure
+
+- `app.py` – Streamlit entry point
+- `battlewords/` – Python package
+  - `models.py` – data models and types
+  - `word_loader.py` – word list loading and validation
+  - `generator.py` – word placement logic
+  - `logic.py` – game mechanics (reveal, guess, scoring)
+  - `ui.py` – Streamlit UI composition
+  - `storage.py` – **NEW**: persistent storage and high scores
+  - `words/wordlist.txt` – candidate words
+- `specs/` – documentation (`specs.md`, `requirements.md`)
+- `tests/` – unit tests
+
+## Data Storage
+
+**Privacy First**: All game data is stored locally on your device in `~/.battlewords/data/`. No data is sent to external servers. Player names are optional and default to "Anonymous".
+
+**Storage Location**:
+- Windows: `C:\Users\<username>\.battlewords\data\`
+- Linux/Mac: `~/.battlewords/data/`
+
+**Files**:
+- `game_results.json` - All completed games
+- `highscores.json` - Top 100 scores
+
+You can delete these files at any time to reset your data.
+

battlewords/__init__.py

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

battlewords/storage.py

@@ -0,0 +1,182 @@
+// file: battlewords/storage.py
+"""
+Storage module for BattleWords game.
+
+Provides functionality for:
+1. Saving/loading game results to local JSON files
+2. Managing high scores and leaderboards
+3. Sharing game IDs via query strings
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field, asdict
+from typing import List, Dict, Optional, Any
+from datetime import datetime
+import json
+import os
+from pathlib import Path
+
+@dataclass
+class GameResult:
+    game_id: str
+    wordlist: str
+    game_mode: str
+    score: int
+    tier: str
+    elapsed_seconds: int
+    words_found: List[str]
+    completed_at: str
+    player_name: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "GameResult":
+        return cls(**data)
+
+@dataclass
+class HighScoreEntry:
+    player_name: str
+    score: int
+    tier: str
+    wordlist: str
+    game_mode: str
+    elapsed_seconds: int
+    completed_at: str
+    game_id: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "HighScoreEntry":
+        return cls(**data)
+
+class GameStorage:
+    def __init__(self, storage_dir: Optional[str] = None):
+        if storage_dir is None:
+            storage_dir = os.path.join(
+                os.path.expanduser("~"),
+                ".battlewords",
+                "data"
+            )
+        self.storage_dir = Path(storage_dir)
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+        self.results_file = self.storage_dir / "game_results.json"
+        self.highscores_file = self.storage_dir / "highscores.json"
+
+    def save_result(self, result: GameResult) -> bool:
+        try:
+            results = self.load_all_results()
+            results.append(result.to_dict())
+            with open(self.results_file, 'w', encoding='utf-8') as f:
+                json.dump(results, f, indent=2, ensure_ascii=False)
+            self._update_highscores(result)
+            return True
+        except Exception as e:
+            print(f"Error saving result: {e}")
+            return False
+
+    def load_all_results(self) -> List[Dict[str, Any]]:
+        if not self.results_file.exists():
+            return []
+        try:
+            with open(self.results_file, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except Exception as e:
+            print(f"Error loading results: {e}")
+            return []
+
+    def get_results_by_game_id(self, game_id: str) -> List[GameResult]:
+        all_results = self.load_all_results()
+        matching = [
+            GameResult.from_dict(r)
+            for r in all_results
+            if r.get("game_id") == game_id
+        ]
+        return sorted(matching, key=lambda x: x.score, reverse=True)
+
+    def _update_highscores(self, result: GameResult) -> None:
+        highscores = self.load_highscores()
+        entry = HighScoreEntry(
+            player_name=result.player_name or "Anonymous",
+            score=result.score,
+            tier=result.tier,
+            wordlist=result.wordlist,
+            game_mode=result.game_mode,
+            elapsed_seconds=result.elapsed_seconds,
+            completed_at=result.completed_at,
+            game_id=result.game_id
+        )
+        highscores.append(entry.to_dict())
+        highscores.sort(key=lambda x: x["score"], reverse=True)
+        highscores = highscores[:100]
+        with open(self.highscores_file, 'w', encoding='utf-8') as f:
+            json.dump(highscores, f, indent=2, ensure_ascii=False)
+
+    def load_highscores(
+        self,
+        wordlist: Optional[str] = None,
+        game_mode: Optional[str] = None,
+        limit: int = 10
+    ) -> List[HighScoreEntry]:
+        if not self.highscores_file.exists():
+            return []
+        try:
+            with open(self.highscores_file, 'r', encoding='utf-8') as f:
+                scores = json.load(f)
+            if wordlist:
+                scores = [s for s in scores if s.get("wordlist") == wordlist]
+            if game_mode:
+                scores = [s for s in scores if s.get("game_mode") == game_mode]
+            scores.sort(key=lambda x: x["score"], reverse=True)
+            return [HighScoreEntry.from_dict(s) for s in scores[:limit]]
+        except Exception as e:
+            print(f"Error loading highscores: {e}")
+            return []
+
+    def get_player_stats(self, player_name: str) -> Dict[str, Any]:
+        all_results = self.load_all_results()
+        player_results = [
+            GameResult.from_dict(r)
+            for r in all_results
+            if r.get("player_name") == player_name
+        ]
+        if not player_results:
+            return {
+                "games_played": 0,
+                "total_score": 0,
+                "average_score": 0,
+                "best_score": 0,
+                "best_tier": None
+            }
+        scores = [r.score for r in player_results]
+        return {
+            "games_played": len(player_results),
+            "total_score": sum(scores),
+            "average_score": sum(scores) / len(scores),
+            "best_score": max(scores),
+            "best_tier": max(player_results, key=lambda x: x.score).tier,
+            "fastest_time": min(r.elapsed_seconds for r in player_results)
+        }
+
+def generate_game_id_from_words(words: List[str]) -> str:
+    import hashlib
+    sorted_words = sorted([w.upper() for w in words])
+    word_string = "".join(sorted_words)
+    hash_obj = hashlib.sha256(word_string.encode('utf-8'))
+    return hash_obj.hexdigest()[:8].upper()
+
+def parse_game_id_from_url() -> Optional[str]:
+    try:
+        import streamlit as st
+        params = st.query_params
+        return params.get("game_id")
+    except Exception:
+        return None
+
+def create_shareable_url(game_id: str, base_url: Optional[str] = None) -> str:
+    if base_url is None:
+        base_url = "https://huggingface.co/spaces/Surn/BattleWords"
+    return f"{base_url}?game_id={game_id}"

claude.md

@@ -3,7 +3,8 @@
 ## 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.
 
-**Current Version:** 0.2.6
+**Current Version:** 0.2.17 (Stable)
+**Next Version:** 0.3.0 (In Development - Storage & Sharing Features)
 **Repository:** https://github.com/Oncorporation/BattleWords.git
 **Live Demo:** https://huggingface.co/spaces/Surn/BattleWords
 
@@ -14,6 +15,10 @@ BattleWords is a vocabulary learning game inspired by Battleship mechanics, buil
 - 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 revealed
+- Incorrect guess history with optional display (enabled by default)
+- 10 incorrect guess limit per game
+- **PLANNED (v0.3.0):** Game sharing via unique game IDs
+- **PLANNED (v0.3.0):** Local persistent storage for results and high scores
 
 ### Scoring Tiers
 - **Fantastic:** 42+ points
@@ -28,6 +33,7 @@ BattleWords is a vocabulary learning game inspired by Battleship mechanics, buil
 - **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)
@@ -37,24 +43,32 @@ BattleWords is a vocabulary learning game inspired by Battleship mechanics, buil
 battlewords/
 ├── app.py                    # Streamlit entry point
 ├── battlewords/              # Main package
-│   ├── __init__.py          # Version: 0.2.6
+│   ├── __init__.py          # Version: 0.2.17
 │   ├── 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 (~1170 lines)
+│   ├── 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
+│   ├── storage.py           # Storage module (v0.3.0 - IN DEVELOPMENT)
 │   ├── version_info.py      # Version display
 │   └── words/               # Word list files
 │       ├── classic.txt      # Default word list
-│       └── wordlist.txt     # Additional words
+│       ├── 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
+├── Dockerfile              # Container deployment
+└── CLAUDE.md               # This file - project context for Claude
 ```
 
 ## Key Features
@@ -63,6 +77,31 @@ battlewords/
 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)
+
+### PLANNED: Storage & Sharing (v0.3.0)
+- **Game ID System:** 8-character deterministic IDs based on word combinations
+  - Format: `?game_id=ABC123` in URL
+  - Same words, different positions for each replay
+  - Enables fair challenges between players
+- **Local Storage:** 
+  - Location: `~/.battlewords/data/`
+  - Files: `game_results.json`, `highscores.json`
+  - Privacy-first: no cloud dependency
+- **High Scores:**
+  - Top 100 scores tracked automatically
+  - Filterable by wordlist and game mode
+  - Optional player names (defaults to "Anonymous")
+- **Player Statistics:**
+  - Games played, average score, best score
+  - Fastest completion time
+  - Per-player history
+
 ### Puzzle Generation
 - Deterministic seeding support for reproducible puzzles
 - Configurable word spacing (spacer: 0-2)
@@ -70,25 +109,55 @@ battlewords/
   - 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
+- **v0.3.0:** Game ID system planned (not yet integrated into Puzzle model)
 
-### UI Components
+### 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
-- **Score Panel:** Real-time scoring with client-side timer
-- **Settings Sidebar:** Word list picker, game mode, spacing, audio controls
-- **Theme System:** Ocean gradient background with animations
-- **Audio System:** Background music with volume control
-
-### Recent Fixes (cc-01 branch)
-- **Radar Alignment Issue:** Fixed inconsistent sizing of animated rings layer
+- **Game Grid:** Interactive 12x12 button grid with responsive layout
+- **Score Panel:** Real-time scoring with client-side JavaScript timer
+- **Settings Sidebar:**
+  - Word list picker (classic, fourth_grade, wordlist)
+  - Game mode selector
+  - Word spacing configuration (0-2)
+  - Audio volume controls (music and effects separate)
+  - Toggle for incorrect guess history display
+- **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
+- **PLANNED (v0.3.0):** High scores expander in sidebar
+- **PLANNED (v0.3.0):** Share challenge button in game over dialog
+- **PLANNED (v0.3.0):** Game ID display during gameplay
+
+### Recent Changes & Branch Status
+**Branch:** cc-01 (Storage and sharing features - v0.3.0 development)
+
+**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
 
+**In Progress (v0.3.0 on cc-01):**
+- Storage module implementation (storage.py created)
+- Game ID system for sharing
+- High score tracking infrastructure
+
 ## Data Models
 
 ### Core Classes
@@ -152,39 +221,83 @@ docker run -p 8501:8501 battlewords
 pytest tests/
 ```
 
-## Current Development Branch
-**Branch:** cc-01
-**Purpose:** Bug fixes and improvements, specifically radar graphic alignment
+## 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)
 
-### Git Configuration
-- **Remote ONCORP:** https://github.com/Oncorporation/BattleWords.git (main remote)
-- **Remote Hugging:** https://huggingface.co/spaces/Surn/BattleWords (deployment)
+### 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
 
-### Beta (0.5.0)
-- Word overlaps on shared letters (crossword-style)
-- Enhanced responsive layout
+### 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
+- Deterministic seed UI for custom puzzles
+- Improved accessibility features
 
-### Full (1.0.0)
-- Daily puzzle mode
-- Practice mode
-- Leaderboards
-- Persistent storage
-- Enhanced UX 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
@@ -193,3 +306,6 @@ pytest tests/
 - 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

specs/requirements.md

@@ -136,94 +136,55 @@ Known Issues / TODO
   - 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.
 
-Beta (0.5.0) – Planned
-- Allow shared-letter overlaps when letters match; deterministic seeding; keyboard navigation.
-
-B) UI and Interaction
-- Cell rendering with consistent sizing and responsive layout (desktop/mobile).
-- Keyboard support for grid navigation and guessing (custom JS via `st.html` or component).
-- Maintain radar behavior and scoring rules.
+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:
-- Grid scales cleanly across typical desktop and mobile widths.
-- Users can enter guesses and move focus via keyboard.
-
-C) Tests
-- Property checks for overlap validity (only same letters may share a cell).
-- Seed reproducibility tests (same seed → identical placements).
-- Optional validation tests for adjacency curation (when enabled).
-
-Phase 2: Full Version (1.0.0)
-Goal: Robust app with polish, persistence, test coverage, and optional advanced features.
-
-A) UX and Visual Polish
-- Cell rendering with consistent sizing and responsive layout (desktop/mobile).
-- Keyboard support for navigation and guessing (custom JS via `st.html` or a component if needed).
-- Animations for reveals and correct guesses (CSS/JS via `st.html` or component).
-- Color-blind friendly palette and accessible contrast.
-- Configurable themes (light/dark) via Streamlit theme config.
-- Streamlit: `st.tabs` for modes/help; `st.popover`/`st.expander` for tips; `st.toast`/`st.warning` for feedback.
-
-B) Game Content and Generation
-- Curated word lists by difficulty; exclude obscure/abusive words.
-- Deterministic seed support to reproduce puzzles (e.g., daily seed based on date).
-- Validation pass to ensure no unintended partial words formed adjacently (content curation rule, optional).
-- Optional generator diagnostics panel for QA using `st.expander` and `st.dataframe`.
-- Streamlit: `st.cache_data` for word lists; `st.cache_resource` if needed for heavier resources.
-
-C) Game Modes and Settings
-- Daily Puzzle mode (same seed for all players per day).
-- Practice mode (random puzzles).
-- Difficulty presets that tweak word selection (common vs. rare) but still keep 2×4, 2×5, 2×6.
-- Optional hint system with limited uses (e.g., reveal a random letter in an unguessed word) with score penalty.
-- Streamlit: mode selection via `st.radio`/`st.segmented_control`; settings via `st.sidebar` with `st.toggle`/`st.slider`.
-
-D) Persistence and Profiles
-- Save/Load local game state (browser cookie or Streamlit session + query params).
-- Cloud persistence via lightweight backend API (FastAPI) or Streamlit secrets + hosted storage for:
-  - User profiles (username only), completed puzzles, scores.
-  - Leaderboards for Daily mode.
-- Privacy notice and opt-in for storing data.
-- Streamlit: `st.text_input` for username; `st.button` to save; call backend via `requests`.
-
-E) Leaderboards and Sharing
-- Global and friends leaderboards (score and completion time if captured; note: game is strategy-first, time is optional).
-- Share result string with spoiler-free grid (similar to popular word games).
-- Streamlit: `st.table`/`st.dataframe` for leaderboards; `st.download_button` or copy-to-clipboard via `st.text_area` + `st.button`.
-
-F) Observability and Quality
-- Logging for generator failures and gameplay events (anonymized).
-- Error boundary UI with recover/retry.
-- Test suite:
-  - Unit: generator, logic, scoring, gating, radar.
-  - Property-based tests for generator (e.g., Hypothesis) to stress placement constraints.
-  - Integration tests that simulate a full game and validate scoring.
-  - Visual regression snapshots of grid/radar (optional).
-- CI/CD with linting (flake8/ruff), type checks (mypy/pyright), tests, and build.
-- Streamlit: developer toggles in an `st.expander` to simulate states; optional `st.fragment` to limit rerenders in hotspots.
-
-G) Performance
-- Optimize generator to avoid excessive retries (precompute candidate slots, shuffle deterministically).
-- Memoize derived UI state.
-- Efficient grid rendering (batch updates or delta rendering where possible in Streamlit).
-- Streamlit: consider `st.fragment` for the grid/radar to avoid full-page rerenders.
-
-H) Internationalization (Optional)
-- i18n-ready strings; language toggle.
-- Locale-specific word lists.
-- Streamlit: language toggle via `st.selectbox`.
-
-I) Security and Abuse Prevention
-- Validate all inputs (guess strings A–Z only).
-- Rate-limit backend endpoints (if any) and sanitize stored data.
-- Streamlit: enforce validation in the submit handler and sanitize displayed content with strict formatting.
-
-J) Deployment
-- Streamlit Community Cloud or containerized deployment (Dockerfile) to any cloud.
-- Environment configuration via `.env` or Streamlit secrets.
-- Streamlit: use `st.secrets` for API keys.
+- 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
+- Phase 1.5 (Storage & Sharing): 2–3 days ⏳ IN PROGRESS
 - Beta (0.5.0): 3–5 days (overlaps, responsive UI, keyboard, deterministic seed)
 - Phase 2 (Full): 1–2 weeks depending on features selected
 

specs/specs.md

@@ -53,12 +53,25 @@ Battlewords is inspired by the classic Battleship game, but uses words instead o
 - 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.
+
+## 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.
+
 ## 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.
 
 ## Word List
 - External list at `battlewords/words/wordlist.txt`.