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

README.md

@@ -23,22 +23,60 @@ BattleWords is a vocabulary learning game inspired by classic Battleship mechani
 
 ## Features
 
+### Core Gameplay
 - 12x12 grid with six hidden words (2x4-letter, 2x5-letter, 2x6-letter)
 - Words placed horizontally or vertically
-- Radar visualization to help locate word boundaries
+- Animated radar visualization showing word boundaries
 - Reveal grid cells and guess words for points
 - Scoring tiers: Good (34–37), Great (38–41), Fantastic (42+)
+- Game ends when all words are guessed or all word letters are revealed
+- Incorrect guess history with tooltip and optional display (enabled by default)
+- 10 incorrect guess limit per game
+- Two game modes: Classic (chain guesses) and Too Easy (single guess per reveal)
+
+### Audio & 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
-- Customizable word lists
+
+### Customization
+- Multiple word lists (classic, fourth_grade, wordlist)
 - Wordlist sidebar controls (picker + one-click sort)
-- Deterministic seed support (Beta/Full)
-- Keyboard navigation and guessing (Beta/Full)
-- Daily and practice modes (Full)
-- Leaderboards, persistence, and advanced features (Full)
-- **Dockerfile-based deployment supported for Hugging Face Spaces and other container platforms**
-- **Game ends when all words are guessed or all word letters are revealed**
-- **Incorrect guess history with tooltip and optional display (enabled by default)**
-- **Challenge Mode:** Shareable game links with leaderboard, remote storage, and multi-user results
+- 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
+
+### 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)
+
+### 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
+
+### Beta (v0.5.0)
+- Word overlaps on shared letters (crossword-style)
+- Enhanced responsive layout for mobile/tablet
+- Keyboard navigation and guessing
+
+### Full (v1.0.0)
+- Daily puzzle mode with global leaderboards
+- Practice mode with hints
+- Multiple difficulty levels
+- Internationalization (i18n) support
 
 ## Challenge Mode & Leaderboard
 
@@ -89,6 +127,27 @@ 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.
+
 ## Folder Structure
 
 - `app.py` – Streamlit entry point
@@ -116,12 +175,19 @@ docker run -p8501:8501 battlewords
 ## Changelog
 
 ### v0.3.0 (planned)
- - Game Sharing: share unique game URLs with friends to challenge them on the same word set.
- - High Scores: local leaderboard tracking top scores by wordlist and game mode.
- - Persistent Storage: all game results saved locally for personal statistics without accounts.
- - Challenge Mode: remote storage of challenge results, multi-user leaderboard, and shareable links.
+ - Local persistent storage for personal game history (offline-capable)
+ - Personal high scores sidebar with filtering
+ - Player statistics tracking (games played, averages, bests)
+
+-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
  
--02.26
+-0.2.26
   - fix copy/share link button
   
 -0.2.25
@@ -438,52 +504,33 @@ 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
-- Top10 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
- - `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
-
-## 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` - Top100 scores
-
-You can delete these files at any time to reset your data.
+## 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.26"
+__version__ = "0.2.27"
 __all__ = ["models", "generator", "logic", "ui", "game_storage"]

battlewords/ui.py

@@ -430,6 +430,9 @@ 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
 
 def _new_game() -> None:
  selected = st.session_state.get("selected_wordlist")
@@ -443,6 +446,9 @@ def _new_game() -> None:
  music_volume = st.session_state.get("music_volume",15)
  effects_volume = st.session_state.get("effects_volume",25)
  enable_sound_effects = st.session_state.get("enable_sound_effects", True)
+ # 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:
     st.session_state.selected_wordlist = selected
@@ -458,6 +464,9 @@ def _new_game() -> None:
  st.session_state.music_volume = music_volume
  st.session_state.effects_volume = effects_volume
  st.session_state.enable_sound_effects = enable_sound_effects
+ # 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
  st.session_state.start_time = datetime.now() # Reset timer on new game
@@ -541,7 +550,8 @@ def _render_header():
                     # Get the challenge SID from session state
                     sid = st.session_state.get("loaded_game_sid")
                     share_html = ""
-                    if sid:
+                    # 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>"
 
@@ -657,6 +667,11 @@ def _render_sidebar():
             st.session_state.show_incorrect_guesses = True
         st.checkbox("Show incorrect guesses", value=st.session_state.show_incorrect_guesses, key="show_incorrect_guesses")
 
+        # NEW: Add Show Challenge Share Links option - default OFF
+        if "show_challenge_share_links" not in st.session_state:
+            st.session_state.show_challenge_share_links = False
+        st.checkbox("Show Challenge Share Links", value=st.session_state.show_challenge_share_links, key="show_challenge_share_links")
+
         # Audio settings
         st.header("Audio")
         tracks = get_audio_tracks()
@@ -1644,100 +1659,45 @@ def _game_over_content(state: GameState) -> None:
                 except Exception as e:
                     st.error(f"Failed to save game: {e}")
         else:
-            # 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>
-                <script>
-                (function() {{
-                  const SHARE_URL = {_share_url_json};                  
-                  const input = document.getElementById('bw-share-url');
-
-                  async function modernCopy(text) {{
-                    if (!navigator.clipboard || !window.isSecureContext) {{
-                      throw new Error('Clipboard API unavailable in this context');
-                    }}
-                    await navigator.clipboard.writeText(text);
-                  }}
-
-                  function legacyCopy(text) {{
-                    const ta = document.createElement('textarea');
-                    ta.value = text;
-                    ta.setAttribute('readonly', '');
-                    ta.style.position = 'fixed';
-                    ta.style.top = '-1000px';
-                    ta.style.left = '-1000px';
-                    document.body.appendChild(ta);
-                    ta.focus();
-                    ta.select();
-                    let ok = false;
-                    try {{
-                      ok = document.execCommand('copy');
-                    }} finally {{
-                      document.body.removeChild(ta);
-                    }}
-                    if (!ok) throw new Error('execCommand failed');
-                  }}
-
-                  btn.addEventListener('click', async () => {{
-                    try {{
-                      try {{
-                        await modernCopy(SHARE_URL);
-                      }} catch (e) {{
-                        legacyCopy(SHARE_URL);
-                      }}
-                      setStatus('Copied!');
-                    }} catch (e) {{
-                      // Final fallback: select input text and ask user to copy
-                      try {{
-                        input.removeAttribute('readonly');
-                        input.focus();
-                        input.select();
-                        input.setSelectionRange(0, input.value.length);
-                        document.execCommand('copy'); // may still work on some browsers
-                        input.setAttribute('readonly', '');
-                        setStatus('Copied!');
-                      }} catch (err) {{
-                        input.focus();
-                        input.select();
-                        setStatus('Press Ctrl+C');
-                      }}
-                    }}
-                  }});
-                }})();
-                </script>
-                """,
-                height=80
-            )
+            # 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("---")
 

claude.md

@@ -3,11 +3,20 @@
 ## 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.17 (Stable)
-**Next Version:** 0.3.0 (In Development - Storage & Sharing Features)
+**Current Version:** 0.2.27 (Stable - Challenge Mode & Remote Storage)
+**Next Version:** 0.3.0 (In Development - Local Player History & Statistics)
 **Repository:** https://github.com/Oncorporation/BattleWords.git
 **Live Demo:** https://huggingface.co/spaces/Surn/BattleWords
 
+## Recent Changes & Branch Status
+
+**Latest (v0.2.27):**
+- New setting: "Show Challenge Share Links" (default OFF)
+  - Header Challenge Mode banner hides the "Share this challenge" link when disabled
+  - Game Over dialog still lets you submit or create a challenge, but hides the generated share URL when disabled (shows a success message instead)
+  - Setting is stored in Streamlit session state and preserved across "New Game"
+  - No changes to `logic.py` or `game_storage.py`; this is a UI-only visibility feature
+
 ## Core Gameplay
 - 12x12 grid with 6 hidden words (2×4-letter, 2×5-letter, 2×6-letter)
 - Words placed horizontally or vertically, no overlaps
@@ -17,8 +26,9 @@ BattleWords is a vocabulary learning game inspired by Battleship mechanics, buil
 - 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
+- **✅ 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
+- **PLANNED (v0.3.0):** Local persistent storage for individual player results and high scores
 
 ### Scoring Tiers
 - **Fantastic:** 42+ points
@@ -90,23 +100,38 @@ battlewords/
 - **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
+### ✅ 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
-- **Local Storage:** 
+  - 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
+
+### PLANNED: Local Player Storage (v0.3.0)
+- **Local Storage:**
   - Location: `~/.battlewords/data/`
   - Files: `game_results.json`, `highscores.json`
-  - Privacy-first: no cloud dependency
-- **High Scores:**
-  - Top 100 scores tracked automatically
+  - Privacy-first: no cloud dependency, offline-capable
+- **Personal High Scores:**
+  - Top 100 scores tracked automatically on local machine
   - Filterable by wordlist and game mode
-  - Optional player names (defaults to "Anonymous")
+  - High score sidebar expander display
 - **Player Statistics:**
   - Games played, average score, best score
   - Fastest completion time
-  - Per-player history
+  - Per-player history on local device
 
 ### Puzzle Generation
 - Deterministic seeding support for reproducible puzzles
@@ -115,7 +140,6 @@ 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 (Current)
 - **Radar Visualization:** Animated matplotlib GIF showing word boundaries
@@ -134,9 +158,14 @@ battlewords/
 - **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
+- **✅ 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:** cc-01 (Storage and sharing features - v0.3.0 development)
@@ -159,7 +188,7 @@ battlewords/
   - 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):**
+**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
@@ -171,18 +200,25 @@ battlewords/
   - `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 showing target score and time
-  - Share button in game over dialog with "Generate Share Link"
-  - Copy-to-clipboard functionality for share URLs
+  - 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 same words, different positions
-- ⏳ High score tracking infrastructure (backend ready, UI pending)
+  - 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
 
@@ -247,6 +283,32 @@ docker run -p 8501:8501 battlewords
 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
+```
+
+**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)

specs/requirements.md

@@ -15,7 +15,9 @@ Streamlit key components (API usage plan)
   - `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.cache_data` to load and filter the word list.
+  - `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.
+
 - 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.
@@ -189,8 +191,10 @@ D) Tests
 - 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
+- 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
 
@@ -212,52 +216,84 @@ Definitions of Done (per task)
 - 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)
+## Phase 1.6: Remote Storage & Challenge Mode (v0.2.20-0.2.27) ✅ COMPLETE
 
-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.
+### 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
-- Use modules from OpenBadge `modules/storage.py`:
+### 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`
-- 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
-
-## Challenge Mode & Remote Storage
-
-- The app must support remote storage of challenge results using Hugging Face datasets.
-- The leaderboard for a shared challenge (`game_id`) must display all user results.
-- **Sorting:** Results are sorted by highest score (descending), then by fastest time (ascending).
-- Each user result is appended to the challenge's `users` array in the remote JSON.
-- The UI must allow submitting results to an existing challenge or creating a new one.
+- 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
+- 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/)

specs/specs.md

@@ -78,11 +78,20 @@ Battlewords is inspired by the classic Battleship game, but uses words instead o
 - 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.
+- Filtered to uppercase A�Z, lengths in {4,5,6}; falls back if < 25 per length.
 
 ## Generator
 - Centralized word loader.
@@ -92,6 +101,58 @@ Battlewords is inspired by the classic Battleship game, but uses words instead o
 - 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.
+
+### 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
+
 ## Copyright
 BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.
 
@@ -113,7 +174,7 @@ High Scores
 - Local highscores remain supported for offline use
 
 UI/UX
-- Show the current `game_id` (sid) and a �Share Challenge� link
+- 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