v0.2.8 - add sound effects, incorrect guess list

.gitattributes

@@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 *.mp3 filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text

README.md

@@ -37,6 +37,7 @@ BattleWords is a vocabulary learning game inspired by classic Battleship mechani
 - 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)**
 
 ## Installation
 1. Clone the repository:
@@ -105,6 +106,15 @@ docker run -p 8501:8501 battlewords
 
 ## Changelog
 
+-0.2.8
+  - Add 10 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

battlewords/__init__.py

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

battlewords/assets/audio/congratulations.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:da52c73b00948b8c7fe0197f62a57af5ee439b5b1acef31c7add3868d23af437
+size 74446

battlewords/assets/audio/correct_guess.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:397af68b9d343f146c1aa897f9bd64fdb646739edfabfb6ead6f2747fc089d2e
+size 50246

battlewords/assets/audio/hit.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:baaf44f8d29b5543d6c3418ae8ea5d8144046362055b95678b552965f3850a6b
+size 25833

battlewords/assets/audio/incorrect_guess.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1cc06c8c57a1f5acd81661723bcfbf945a253110279b9db7eaca02f89c61667d
+size 49663

battlewords/assets/audio/miss.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e1d774c8241e9295a813f29127e2cb2c148b2ede6845b8ce1702ed970158fc04
+size 25834

battlewords/audio.py

@@ -10,9 +10,15 @@ def get_audio_tracks() -> list[tuple[str, str]]:
     audio_dir = _get_audio_dir()
     if not os.path.isdir(audio_dir):
         return []
-    files = [f for f in os.listdir(audio_dir) if f.lower().endswith(".mp3")]
-    files.sort()
-    return [(os.path.splitext(f)[0].replace("_", " ").title(), os.path.join(audio_dir, f)) for f in files]
+    # Only include .mp3 files, ignore .wav files
+    tracks = []
+    for fname in os.listdir(audio_dir):
+        if fname.lower().endswith('.mp3'):
+            path = os.path.join(audio_dir, fname)
+            # Use the filename without extension as the display name
+            name = os.path.splitext(fname)[0]
+            tracks.append((name, path))
+    return tracks
 
 @st.cache_data(show_spinner=False)
 def _load_audio_data_url(path: str) -> str:
@@ -20,6 +26,7 @@ def _load_audio_data_url(path: str) -> str:
     import base64, mimetypes
     mime, _ = mimetypes.guess_type(path)
     if not mime:
+        # Default to mp3 to avoid blocked playback if unknown
         mime = "audio/mpeg"
     with open(path, "rb") as fp:
         encoded = base64.b64encode(fp.read()).decode("ascii")
@@ -130,4 +137,82 @@ def _inject_audio_control_sync():
         </script>
         ''',
         height=0,
+    )
+
+# Sound effects functionality
+def get_sound_effect_files() -> dict[str, str]:
+    """
+    Return dictionary of sound effect name -> absolute path.
+    Prefers .mp3 files; falls back to .wav if no .mp3 is found.
+    """
+    audio_dir = _get_audio_dir()
+    if not os.path.isdir(audio_dir):
+        return {}
+
+    effect_names = [
+        "correct_guess",
+        "incorrect_guess",
+        "hit",
+        "miss",
+        "congratulations",
+    ]
+
+    def _find_effect_file(base: str) -> Optional[str]:
+        # Prefer mp3, then wav for backward compatibility
+        for ext in (".mp3", ".wav"):
+            path = os.path.join(audio_dir, f"{base}{ext}")
+            if os.path.exists(path):
+                return path
+        return None
+
+    result: dict[str, str] = {}
+    for name in effect_names:
+        path = _find_effect_file(name)
+        if path:
+            result[name] = path
+
+    return result
+
+def play_sound_effect(effect_name: str, volume: float = 0.5) -> None:
+    """
+    Play a sound effect by name.
+
+    Args:
+        effect_name: One of 'correct_guess', 'incorrect_guess', 'hit', 'miss', 'congratulations'
+        volume: Volume level (0.0 to 1.0)
+    """
+    from streamlit.components.v1 import html as _html
+
+    sound_files = get_sound_effect_files()
+
+    if effect_name not in sound_files:
+        return  # Sound file doesn't exist, silently skip
+
+    sound_path = sound_files[effect_name]
+    sound_data_url = _load_audio_data_url(sound_path)
+
+    # Clamp volume
+    vol = max(0.0, min(1.0, float(volume)))
+
+    # Play sound effect using a unique audio element
+    _html(
+        f"""
+        <script>
+        (function(){{
+          const doc = window.parent?.document || document;
+          const audio = doc.createElement('audio');
+          audio.src = "{sound_data_url}";
+          audio.volume = {vol:.3f};
+          audio.style.display = 'none';
+          doc.body.appendChild(audio);
+
+          // Play and remove after playback
+          audio.play().catch(e => console.error('Sound effect play error:', e));
+          audio.addEventListener('ended', () => {{
+            doc.body.removeChild(audio);
+          }});
+        }})();
+        </script>
+        """,
+        height=0,
     )

battlewords/generate_sounds.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""
+Standalone script to generate sound effects using Hugging Face API.
+Uses only built-in Python libraries (no external dependencies).
+"""
+
+import os
+import json
+import urllib.request
+import time
+from pathlib import Path
+
+# Load environment variables from .env if present
+env_path = Path(__file__).parent / ".env"
+if env_path.exists():
+    with open(env_path) as f:
+        for line in f:
+            if line.strip() and not line.startswith("#"):
+                key, _, value = line.strip().partition("=")
+                os.environ[key] = value
+
+# Get Hugging Face API token from environment variable
+HF_API_TOKEN = os.environ.get("HF_API_TOKEN")
+if not HF_API_TOKEN:
+    print("Warning: HF_API_TOKEN not set in environment or .env file.")
+
+# Using your UnlimitedMusicGen Gradio Space
+SPACE_URL = "https://surn-unlimitedmusicgen.hf.space"
+GRADIO_API_URL = f"{SPACE_URL}/api/predict"
+GRADIO_STATUS_URL = f"{SPACE_URL}/call/predict/{{event_id}}"
+
+# Sound effects to generate
+EFFECT_PROMPTS = {
+    "correct_guess": {"prompt": "A short, sharp ding sound for a correct guess", "duration": 2},
+    "incorrect_guess": {"prompt": "A low buzz sound for an incorrect guess", "duration": 2},
+    "miss": {"prompt": "A soft thud sound for a miss", "duration": 1},
+    "hit": {"prompt": "A bright chime sound for a hit", "duration": 1},
+    "congratulations": {"prompt": "A triumphant fanfare sound for congratulations", "duration": 3}
+}
+
+def generate_sound_effect_gradio(effect_name: str, prompt: str, duration: float, output_dir: Path) -> bool:
+    """Generate a single sound effect using Gradio API (async call)."""
+
+    print(f"\nGenerating: {effect_name}")
+    print(f"  Prompt: {prompt}")
+    print(f"  Duration: {duration}s")
+
+    # Step 1: Submit generation request
+    payload = json.dumps({
+        "data": [prompt, duration]
+    }).encode('utf-8')
+
+    headers = {
+        "Content-Type": "application/json"
+    }
+
+    try:
+        print(f"  Submitting request to Gradio API...")
+
+        # Submit the job
+        req = urllib.request.Request(GRADIO_API_URL, data=payload, headers=headers, method='POST')
+
+        with urllib.request.urlopen(req, timeout=30) as response:
+            if response.status == 200:
+                result = json.loads(response.read().decode())
+                event_id = result.get("event_id")
+
+                if not event_id:
+                    print(f"  ✗ No event_id returned")
+                    return False
+
+                print(f"  Job submitted, event_id: {event_id}")
+
+                # Step 2: Poll for results
+                status_url = GRADIO_STATUS_URL.format(event_id=event_id)
+
+                for poll_attempt in range(30):  # Poll for up to 5 minutes
+                    time.sleep(10)
+                    print(f"  Polling for results (attempt {poll_attempt + 1}/30)...")
+
+                    status_req = urllib.request.Request(status_url, headers=headers)
+
+                    try:
+                        with urllib.request.urlopen(status_req, timeout=30) as status_response:
+                            # Gradio returns streaming events, read until we get the result
+                            for line in status_response:
+                                line = line.decode('utf-8').strip()
+                                if line.startswith('data: '):
+                                    event_data = json.loads(line[6:])  # Remove 'data: ' prefix
+
+                                    if event_data.get('msg') == 'process_completed':
+                                        # Get the audio file URL
+                                        output_data = event_data.get('output', {}).get('data', [])
+                                        if output_data and len(output_data) > 0:
+                                            audio_url = output_data[0].get('url')
+                                            if audio_url:
+                                                # Download the audio file
+                                                full_audio_url = f"https://surn-unlimitedmusicgen.hf.space{audio_url}"
+                                                print(f"  Downloading from: {full_audio_url}")
+
+                                                audio_req = urllib.request.Request(full_audio_url)
+                                                with urllib.request.urlopen(audio_req, timeout=30) as audio_response:
+                                                    audio_data = audio_response.read()
+
+                                                    # Save to file
+                                                    output_path = output_dir / f"{effect_name}.wav"
+                                                    with open(output_path, "wb") as f:
+                                                        f.write(audio_data)
+
+                                                    print(f"  ✓ Success! Saved to: {output_path}")
+                                                    print(f"  File size: {len(audio_data)} bytes")
+                                                    return True
+
+                                    elif event_data.get('msg') == 'process_error':
+                                        print(f"  ✗ Generation error: {event_data.get('output')}")
+                                        return False
+
+                    except Exception as poll_error:
+                        print(f"  Polling error: {poll_error}")
+                        continue
+
+                print(f"  ✗ Timeout waiting for generation")
+                return False
+
+            else:
+                print(f"  ✗ Error {response.status}: {response.read().decode()}")
+                return False
+
+    except Exception as e:
+        print(f"  ✗ Error: {e}")
+        return False
+
+def main():
+    """Generate all sound effects."""
+
+    print("=" * 70)
+    print("Sound Effects Generator for BattleWords")
+    print("=" * 70)
+    print(f"Using UnlimitedMusicGen Gradio API")
+    print(f"API URL: {GRADIO_API_URL}")
+    print(f"\nGenerating {len(EFFECT_PROMPTS)} sound effects...\n")
+
+    # Create output directory
+    output_dir = Path(__file__).parent / "assets" / "audio"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    print(f"Output directory: {output_dir}\n")
+
+    # Generate each effect
+    success_count = 0
+    for effect_name, config in EFFECT_PROMPTS.items():
+        if generate_sound_effect_gradio(
+            effect_name,
+            config["prompt"],
+            config["duration"],
+            output_dir
+        ):
+            success_count += 1
+
+        # Small delay between requests
+        if effect_name != list(EFFECT_PROMPTS.keys())[-1]:
+            print("  Waiting 5 seconds before next request...")
+            time.sleep(5)
+
+    print("\n" + "=" * 70)
+    print(f"Generation complete! {success_count}/{len(EFFECT_PROMPTS)} successful")
+    print("=" * 70)
+
+    if success_count == len(EFFECT_PROMPTS):
+        print("\n✓ All sound effects generated successfully!")
+    else:
+        print(f"\n⚠ {len(EFFECT_PROMPTS) - success_count} sound effects failed to generate")
+
+if __name__ == "__main__":
+    main()

battlewords/sounds.py

@@ -2,61 +2,157 @@
 
 import os
 import tempfile
-import torch
-from diffusers import StableAudioPipeline
-import scipy.io.wavfile as wav
 import base64
+import requests
+import time
+from io import BytesIO
+from pathlib import Path
 
-# Predefined prompts for sound effects
+# Load environment variables from .env file
+def _load_env():
+    """Load .env file from project root"""
+    env_path = Path(__file__).parent.parent / ".env"
+    if env_path.exists():
+        with open(env_path) as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    key, value = line.split("=", 1)
+                    os.environ.setdefault(key.strip(), value.strip())
+
+_load_env()
+
+# Predefined prompts for sound effects: key: {"prompt": text, "duration": seconds}
 EFFECT_PROMPTS = {
-    "correct guess": "A short, sharp ding sound for a correct guess",
-    "incorrect guess": "A low buzz sound for an incorrect guess",
-    "miss": "A soft thud sound for a miss",
-    "hit": "A bright chime sound for a hit",
-    "congratulations": "A triumphant fanfare sound for congratulations"
+    "correct_guess": {"prompt": "A short, sharp ding sound for a correct guess", "duration": 2},
+    "incorrect_guess": {"prompt": "A low buzz sound for an incorrect guess", "duration": 2},
+    "miss": {"prompt": "A soft thud sound for a miss", "duration": 1},
+    "hit": {"prompt": "A bright chime sound for a hit", "duration": 1},
+    "congratulations": {"prompt": "A triumphant fanfare sound for congratulations", "duration": 3}
 }
 
 _sound_cache = {}
 
-def generate_sound_effect(effect: str) -> str:
+# Hugging Face Inference API configuration
+# Loaded from .env file or environment variable: HF_API_TOKEN
+HF_API_TOKEN = os.environ.get("HF_API_TOKEN", None)
+if HF_API_TOKEN:
+    print(f"Using HF_API_TOKEN: {HF_API_TOKEN[:10]}...")
+HF_API_URL = "https://api-inference.huggingface.co/models/facebook/audiogen-medium"
+
+def generate_sound_effect(effect: str, save_to_assets: bool = False, use_api: str = "huggingface") -> str:
     """
-    Generate a sound effect using Stable Audio Open based on the effect string.
-    Returns the path to the generated WAV file.
+    Generate a sound effect using external API based on the effect string.
+    Returns the path to the generated audio file.
+
+    Args:
+        effect: Name of the effect (must be in EFFECT_PROMPTS)
+        save_to_assets: If True, save to battlewords/assets/audio/ instead of temp directory
+        use_api: API to use - "huggingface" (default) or "replicate"
     """
     if effect not in EFFECT_PROMPTS:
         raise ValueError(f"Unknown effect: {effect}. Available effects: {list(EFFECT_PROMPTS.keys())}")
 
-    # Check cache first
-    if effect in _sound_cache:
-        return _sound_cache[effect]
-
-    # Load the model (cached globally)
-    if not hasattr(generate_sound_effect, 'pipe'):
-        generate_sound_effect.pipe = StableAudioPipeline.from_pretrained(
-            "stabilityai/stable-audio-open-1.0",
-            torch_dtype=torch.float16
-        )
-        if torch.cuda.is_available():
-            generate_sound_effect.pipe = generate_sound_effect.pipe.to("cuda")
-
-    prompt = EFFECT_PROMPTS[effect]
-
-    # Generate audio
-    audio = generate_sound_effect.pipe(
-        prompt,
-        duration=2,  # Short duration for sound effects
-        num_inference_steps=50
-    ).audio
-
-    # Save to temporary file
-    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmpfile:
-        wav.write(tmpfile.name, 44100, audio[0])
-        path = tmpfile.name
+    # Check cache first (only for temp files)
+    if effect in _sound_cache and not save_to_assets:
+        if os.path.exists(_sound_cache[effect]):
+            return _sound_cache[effect]
+
+    effect_config = EFFECT_PROMPTS[effect]
+    prompt = effect_config["prompt"]
+    duration = effect_config["duration"]
+
+    print(f"Generating sound effect: {effect}")
+    print(f"  Prompt: {prompt}")
+    print(f"  Duration: {duration}s")
+    print(f"  Using API: {use_api}")
+
+    audio_bytes = None
+
+    if use_api == "huggingface":
+        audio_bytes = _generate_via_huggingface(prompt, duration)
+    else:
+        raise ValueError(f"Unknown API: {use_api}")
+
+    if audio_bytes is None:
+        raise RuntimeError(f"Failed to generate sound effect: {effect}")
+
+    # Determine save location
+    if save_to_assets:
+        # Save to assets directory
+        assets_dir = os.path.join(os.path.dirname(__file__), "assets", "audio")
+        os.makedirs(assets_dir, exist_ok=True)
+        filename = f"{effect}.wav"
+        path = os.path.join(assets_dir, filename)
+        with open(path, "wb") as f:
+            f.write(audio_bytes)
+        print(f"  Saved to: {path}")
+    else:
+        # Save to temporary file
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmpfile:
+            tmpfile.write(audio_bytes)
+            path = tmpfile.name
+            print(f"  Saved to: {path}")
 
     # Cache the path
     _sound_cache[effect] = path
     return path
 
+def _generate_via_huggingface(prompt: str, duration: float, max_retries: int = 3) -> bytes:
+    """
+    Generate audio using Hugging Face Inference API.
+    Uses facebook/audiogen-medium model for sound effects.
+    """
+    headers = {}
+    if HF_API_TOKEN:
+        headers["Authorization"] = f"Bearer {HF_API_TOKEN}"
+
+    payload = {
+        "inputs": prompt,
+        "parameters": {
+            "duration": duration
+        }
+    }
+
+    for attempt in range(max_retries):
+        try:
+            print(f"  Calling Hugging Face API (attempt {attempt + 1}/{max_retries})...")
+            response = requests.post(HF_API_URL, headers=headers, json=payload, timeout=60)
+
+            if response.status_code == 503:
+                # Model is loading, wait and retry
+                print(f"  Model loading, waiting 10 seconds...")
+                time.sleep(10)
+                continue
+
+            if response.status_code == 200:
+                print(f"  Success! Received {len(response.content)} bytes")
+                return response.content
+            else:
+                print(f"  Error {response.status_code}: {response.text}")
+                if attempt < max_retries - 1:
+                    time.sleep(5)
+                    continue
+                else:
+                    raise RuntimeError(f"API request failed: {response.status_code} - {response.text}")
+
+        except requests.exceptions.Timeout:
+            print(f"  Request timed out")
+            if attempt < max_retries - 1:
+                time.sleep(5)
+                continue
+            else:
+                raise RuntimeError("API request timed out after multiple attempts")
+        except Exception as e:
+            print(f"  Error: {e}")
+            if attempt < max_retries - 1:
+                time.sleep(5)
+                continue
+            else:
+                raise
+
+    return None
+
 def get_sound_effect_path(effect: str) -> str:
     """
     Get the path to a sound effect, generating it if necessary.
@@ -71,4 +167,29 @@ def get_sound_effect_data_url(effect: str) -> str:
     with open(path, "rb") as f:
         data = f.read()
     encoded = base64.b64encode(data).decode()
-    return f"data:audio/wav;base64,{encoded}"
+    return f"data:audio/wav;base64,{encoded}"
+
+def generate_all_effects(save_to_assets: bool = True):
+    """
+    Generate all sound effects defined in EFFECT_PROMPTS.
+
+    Args:
+        save_to_assets: If True, save to battlewords/assets/audio/ directory
+    """
+    print(f"\nGenerating {len(EFFECT_PROMPTS)} sound effects...")
+    print("=" * 60)
+
+    for effect_name in EFFECT_PROMPTS.keys():
+        try:
+            generate_sound_effect(effect_name, save_to_assets=save_to_assets)
+            print()
+        except Exception as e:
+            print(f"ERROR generating {effect_name}: {e}")
+            print()
+
+    print("=" * 60)
+    print("Sound effect generation complete!")
+
+if __name__ == "__main__":
+    # Generate all sound effects when run as a script
+    generate_all_effects(save_to_assets=True)

battlewords/ui.py

@@ -24,6 +24,7 @@ from .audio import (
     _load_audio_data_url,
     _mount_background_audio,
     _inject_audio_control_sync,
+    play_sound_effect,
 )
 
 st.set_page_config(initial_sidebar_state="collapsed")
@@ -267,6 +268,12 @@ def _init_session() -> None:
     # Ensure game_mode is set
     if "game_mode" not in st.session_state:
         st.session_state.game_mode = "classic"
+    # Initialize incorrect guesses tracking
+    if "incorrect_guesses" not in st.session_state:
+        st.session_state.incorrect_guesses = []
+    # Initialize show_incorrect_guesses to True by default
+    if "show_incorrect_guesses" not in st.session_state:
+        st.session_state.show_incorrect_guesses = True
 
 
 def _new_game() -> None:
@@ -274,6 +281,7 @@ def _new_game() -> None:
     mode = st.session_state.get("game_mode")
     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)
     # --- Preserve music settings ---
     music_enabled = st.session_state.get("music_enabled", False)
     music_track_path = st.session_state.get("music_track_path")
@@ -285,6 +293,7 @@ def _new_game() -> None:
         st.session_state.game_mode = mode
     st.session_state.show_grid_ticks = show_grid_ticks
     st.session_state.spacer = spacer
+    st.session_state.show_incorrect_guesses = show_incorrect_guesses
     # --- Restore music settings ---
     st.session_state.music_enabled = music_enabled
     if music_track_path:
@@ -294,6 +303,7 @@ def _new_game() -> None:
     st.session_state.radar_gif_signature = None
     st.session_state.start_time = datetime.now()  # Reset timer on new game
     st.session_state.end_time = None
+    st.session_state.incorrect_guesses = []  # Clear incorrect guesses for new game
     _init_session()
 
 
@@ -392,6 +402,11 @@ def _render_sidebar():
             key="spacer"
         )
 
+        # Add Show Incorrect Guesses option - now enabled by default
+        if "show_incorrect_guesses" not in st.session_state:
+            st.session_state.show_incorrect_guesses = True
+        st.checkbox("Show incorrect guesses", value=st.session_state.show_incorrect_guesses, key="show_incorrect_guesses")
+
         # Audio settings
         st.header("Audio")
         tracks = get_audio_tracks()
@@ -785,6 +800,14 @@ def _render_grid(state: GameState, letter_map, show_grid_ticks: bool = True):
         reveal_cell(state, letter_map, clicked)
         st.session_state.letter_map = build_letter_map(st.session_state.puzzle)
         _sync_back(state)
+
+        # Play sound effect based on hit or miss
+        action = (state.last_action or "").strip()
+        if action.startswith("Revealed '"):
+            play_sound_effect("hit", volume=0.5)
+        elif action.startswith("Revealed empty"):
+            play_sound_effect("miss", volume=0.5)
+
         st.rerun()
 
 def _sort_wordlist(filename):
@@ -871,19 +894,69 @@ def _render_correct_try_again(state: GameState):
 
 
 def _render_guess_form(state: GameState):    
-    with st.form("guess_form",width=300,clear_on_submit=True):
+    # Initialize incorrect guesses list in session state (safety check)
+    if "incorrect_guesses" not in st.session_state:
+        st.session_state.incorrect_guesses = []
+
+    # Prepare tooltip text for native browser tooltip
+    recent_incorrect = st.session_state.incorrect_guesses[-10:]
+    if recent_incorrect:
+        tooltip_text = "Recent incorrect guesses:\n" + "\n".join(recent_incorrect)
+    else:
+        tooltip_text = "No incorrect guesses yet"
+    
+    # Add CSS for the incorrect guesses display
+    st.markdown(
+        """
+        <style>
+        .bw-incorrect-guesses {
+            font-size: 0.85rem;
+            color: #ff9999;
+            margin-top: 4px;
+            padding: 4px 8px;
+            background: rgba(255, 255, 255, 0.05);
+            border-radius: 4px;
+            font-style: italic;
+        }
+        </style>
+        """,
+        unsafe_allow_html=True,
+    )
+    
+    with st.form("guess_form", width=300, clear_on_submit=True):
         col1, col2 = st.columns([2, 1], vertical_alignment="bottom")
         with col1:
-            guess_text = st.text_input("Your Guess", value="", max_chars=10, width=200, key="guess_input")
+            guess_text = st.text_input(
+                "Your Guess", 
+                value="", 
+                max_chars=10, 
+                width=200, 
+                key="guess_input",
+                help=tooltip_text  # Use Streamlit's built-in help parameter for tooltip
+            )
         with col2:
-            submitted = st.form_submit_button("OK", disabled=not state.can_guess, width=100,key="guess_submit")
+            submitted = st.form_submit_button("OK", disabled=not state.can_guess, width=100, key="guess_submit")
+        
+        # Show compact list below input if setting is enabled
+        if st.session_state.get("show_incorrect_guesses", False) and recent_incorrect:
+            st.markdown(
+                f'<div class="bw-incorrect-guesses">Recent: {", ".join(recent_incorrect)}</div>',
+                unsafe_allow_html=True,
+            )
+        
         if submitted:
             correct, _ = guess_word(state, guess_text)
-            _sync_back(state)            
+            _sync_back(state)
             # Invalidate radar GIF cache if guess changed the set of guessed words
             if correct:
                 st.session_state.radar_gif_path = None
                 st.session_state.radar_gif_signature = None
+                play_sound_effect("correct_guess", volume=0.6)
+            else:
+                # Update incorrect guesses list - keep only last 10
+                st.session_state.incorrect_guesses.append(guess_text)
+                st.session_state.incorrect_guesses = st.session_state.incorrect_guesses[-10:]
+                play_sound_effect("incorrect_guess", volume=0.5)
             st.rerun()
 
 
@@ -993,6 +1066,9 @@ def _render_score_panel(state: GameState):
 # -------------------- Game Over Dialog --------------------
 
 def _game_over_content(state: GameState) -> None:
+    # Play congratulations sound when game ends
+    play_sound_effect("congratulations", volume=0.7)
+
     # Set end_time if not already set
     if state.end_time is None:
         st.session_state.end_time = datetime.now()

claude.md

@@ -0,0 +1,195 @@
+# BattleWords - Project Context
+
+## 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
+**Repository:** https://github.com/Oncorporation/BattleWords.git
+**Live Demo:** https://huggingface.co/spaces/Surn/BattleWords
+
+## Core Gameplay
+- 12x12 grid with 6 hidden words (2×4-letter, 2×5-letter, 2×6-letter)
+- Words placed horizontally or vertically, no overlaps
+- 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 revealed
+
+### Scoring Tiers
+- **Fantastic:** 42+ points
+- **Great:** 38-41 points
+- **Good:** 34-37 points
+- **Keep practicing:** < 34 points
+
+## Technical Architecture
+
+### Technology Stack
+- **Framework:** Streamlit 1.50.0
+- **Language:** Python 3.12.8
+- **Visualization:** Matplotlib, NumPy
+- **Data Processing:** Pandas, Altair
+- **Testing:** Pytest
+- **Code Quality:** Flake8, MyPy
+- **Package Manager:** UV (modern Python package manager)
+
+### Project Structure
+```
+battlewords/
+├── app.py                    # Streamlit entry point
+├── battlewords/              # Main package
+│   ├── __init__.py          # Version: 0.2.6
+│   ├── 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)
+│   ├── word_loader.py       # Word list management
+│   ├── audio.py             # Background music system
+│   ├── version_info.py      # Version display
+│   └── words/               # Word list files
+│       ├── classic.txt      # Default word list
+│       └── wordlist.txt     # Additional words
+├── tests/                   # Unit tests
+├── specs/                   # Documentation
+├── .env                     # Environment variables
+├── pyproject.toml          # Project metadata
+├── requirements.txt        # Dependencies
+├── uv.lock                 # UV lock file
+└── Dockerfile              # Container deployment
+```
+
+## Key Features
+
+### Game Modes
+1. **Classic Mode:** Allows consecutive guessing after correct answers
+2. **Too Easy Mode:** Single guess per reveal
+
+### 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
+- **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
+  - 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
+
+## 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/
+```
+
+## Current Development Branch
+**Branch:** cc-01
+**Purpose:** Bug fixes and improvements, specifically radar graphic alignment
+
+### Git Configuration
+- **Remote ONCORP:** https://github.com/Oncorporation/BattleWords.git (main remote)
+- **Remote Hugging:** https://huggingface.co/spaces/Surn/BattleWords (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
+
+## Future Roadmap
+
+### Beta (0.5.0)
+- Word overlaps on shared letters (crossword-style)
+- Enhanced responsive layout
+- Keyboard navigation and guessing
+- Deterministic seed UI
+
+### Full (1.0.0)
+- Daily puzzle mode
+- Practice mode
+- Leaderboards
+- Persistent storage
+- Enhanced UX features
+
+## Deployment Targets
+- **Hugging Face Spaces:** Primary deployment platform
+- **Docker:** Containerized deployment for any platform
+- **Local:** Development and testing
+
+## 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`

requirements.txt

@@ -6,4 +6,5 @@ numpy
 Pillow
 pytest
 flake8
-mypy
+mypy
+requests