Add timer, UI updates, and radar scope improvements

Updated the `README.md` to reflect version `0.2.6` and added changelog entries for new features and fixes. Incremented the version in `__init__.py` to `0.2.6`.

Renamed `game_mode` from `"standard"` to `"classic"` across multiple files for consistency. Added a timer feature with `start_time` and `end_time` fields in `GameState`, updated session initialization and new game logic, and displayed the timer in the score panel and game-over dialog. Injected a client-side JavaScript timer updater for real-time updates.

Removed unused binary files (`scope.gif`, `scope_blue.gif`, `scope_blue.png`) and updated radar scope rendering logic to dynamically handle assets and improve visual alignment. Added new assets (`scope_blue.png`, `scope_blue.gif`) for radar scope rendering.

Improved the layout and styling of the score summary and game-over dialog. Adjusted radar rendering parameters for better clarity. Refactored and cleaned up the codebase for consistency and maintainability.

README.md

@@ -105,6 +105,11 @@ docker run -p 8501:8501 battlewords
 
 ## Changelog
 
+-0.2.6
+  - fix sonar grid alignment
+  - improve score summary layout and styling
+  - Add timer to game display in sidebar
+
 - 0.2.5
   - fix finale pop up issue
   - make grid cells square on wider devices

battlewords/__init__.py

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

battlewords/logic.py

@@ -114,7 +114,7 @@ def guess_word(state: GameState, guess_text: str) -> Tuple[bool, int]:
     state.guessed.add(target.text)
 
     state.last_action = f"Correct! +{points} points for {target.text}."
-    if state.game_mode == "standard":
+    if state.game_mode == "classic":
         state.can_guess = True  # <-- Allow another guess after a correct guess
     else:
         state.can_guess = False

battlewords/models.py

@@ -88,7 +88,7 @@ class GameState:
     score: int
     last_action: str
     can_guess: bool
-    game_mode: Literal["standard", "too easy"] = "standard"
+    game_mode: Literal["classic", "too easy"] = "classic"
     points_by_word: Dict[str, int] = field(default_factory=dict)
     start_time: Optional[datetime] = None
     end_time: Optional[datetime] = None

battlewords/ui.py

@@ -10,6 +10,8 @@ import tempfile
 import os
 from PIL import Image
 import numpy as np
+import time
+from datetime import datetime
 
 from .generator import generate_puzzle, sort_word_file
 from .logic import build_letter_map, reveal_cell, guess_word, is_game_over, compute_tier
@@ -244,7 +246,7 @@ def _init_session() -> None:
     if "selected_wordlist" not in st.session_state and files:
         st.session_state.selected_wordlist = "classic.txt"
     if "game_mode" not in st.session_state:
-        st.session_state.game_mode = "standard"
+        st.session_state.game_mode = "classic"
 
     words = load_word_list(st.session_state.get("selected_wordlist"))
     puzzle = generate_puzzle(grid_size=12, words_by_len=words)
@@ -259,10 +261,12 @@ def _init_session() -> None:
     st.session_state.points_by_word = {}
     st.session_state.letter_map = build_letter_map(puzzle)
     st.session_state.initialized = True
-    st.session_state.radar_gif_path = None  # Add this line
+    st.session_state.radar_gif_path = None
+    st.session_state.start_time = datetime.now()  # Set timer on first game
+    st.session_state.end_time = None
     # Ensure game_mode is set
     if "game_mode" not in st.session_state:
-        st.session_state.game_mode = "standard"
+        st.session_state.game_mode = "classic"
 
 
 def _new_game() -> None:
@@ -286,8 +290,10 @@ def _new_game() -> None:
     if music_track_path:
         st.session_state.music_track_path = music_track_path
     st.session_state.music_volume = music_volume
-    st.session_state.radar_gif_path = None  # Reset radar GIF path
-    st.session_state.radar_gif_signature = None  # Reset signature
+    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
+    st.session_state.end_time = None
     _init_session()
 
 
@@ -300,8 +306,10 @@ def _to_state() -> GameState:
         score=st.session_state.score,
         last_action=st.session_state.last_action,
         can_guess=st.session_state.can_guess,
-        game_mode=st.session_state.get("game_mode", "standard"),
+        game_mode=st.session_state.get("game_mode", "classic"),
         points_by_word=st.session_state.points_by_word,
+        start_time=st.session_state.get("start_time"),
+        end_time=st.session_state.get("end_time"),
     )
 
 
@@ -331,8 +339,8 @@ def _render_sidebar():
         st.header("SETTINGS")        
 
         st.header("Game Mode")
-        game_modes = ["standard", "too easy"]
-        default_mode = "standard"
+        game_modes = ["classic", "too easy"]
+        default_mode = "classic"
         if "game_mode" not in st.session_state:
             st.session_state.game_mode = default_mode
         current_mode = st.session_state.game_mode
@@ -440,21 +448,35 @@ def _render_sidebar():
         _inject_audio_control_sync()
         st.markdown(versions_html(), unsafe_allow_html=True)
 
-def get_scope_image(uid: str, size=4, bgcolor="none", scope_color="green"):
-    """Return a per-puzzle pre-rendered scope image by UID."""
-    # Use a temp directory so multiple tabs/users don't clash and avoid package writes.
+def get_scope_image(uid: str, size=4, bgcolor="none", scope_color="green", img_name="scope_blue.png"):
+    """
+    Return a per-puzzle pre-rendered scope image by UID.
+    1. Check for cached/generated image in temp dir.
+    2. If not found, use assets/scope.gif.
+    3. If neither exists, generate and save a new image.
+    """
     base_dir = os.path.join(tempfile.gettempdir(), "battlewords_scopes")
     os.makedirs(base_dir, exist_ok=True)
     scope_path = os.path.join(base_dir, f"scope_{uid}.png")
-    if not os.path.exists(scope_path):
-        fig, ax = _create_radar_scope(size=size, bgcolor=bgcolor, scope_color=scope_color)
-        imgscope = fig_to_pil_rgba(fig)
-        imgscope.save(scope_path)
-        plt.close(fig)
-    return Image.open(scope_path)
+
+    # 1. Use cached/generated image if it exists
+    if os.path.exists(scope_path):
+        return Image.open(scope_path)
+
+    # 2. Fallback to assets/scope.gif if available
+    assets_scope_path = os.path.join(os.path.dirname(__file__), "assets", img_name)
+    if os.path.exists(assets_scope_path):
+        return Image.open(assets_scope_path)
+
+    # 3. Otherwise, generate and save a new image
+    fig, ax = _create_radar_scope(size=size, bgcolor=bgcolor, scope_color=scope_color)
+    imgscope = fig_to_pil_rgba(fig)
+    imgscope.save(scope_path)
+    plt.close(fig)
+    return imgscope
 
 def _create_radar_scope(size=4, bgcolor="none", scope_color="green"):
-    fig, ax = plt.subplots(figsize=(size, size), dpi=100)
+    fig, ax = plt.subplots(figsize=(size, size), dpi=96)
     ax.set_facecolor(bgcolor)
     fig.patch.set_alpha(0.5)
     ax.set_zorder(0)
@@ -493,7 +515,7 @@ def _create_radar_scope(size=4, bgcolor="none", scope_color="green"):
     
     return fig, ax
 
-def _render_radar(puzzle: Puzzle, size: int, r_max: float = 0.85, max_frames: int = 30, sinusoid_expand: bool = True, stagger_radar: bool = False, show_ticks: bool = True):
+def _render_radar(puzzle: Puzzle, size: int, r_max: float = 0.8, max_frames: int = 30, sinusoid_expand: bool = True, stagger_radar: bool = False, show_ticks: bool = True):
     import numpy as np
     import matplotlib.pyplot as plt
     from matplotlib.animation import FuncAnimation, PillowWriter
@@ -507,6 +529,10 @@ def _render_radar(puzzle: Puzzle, size: int, r_max: float = 0.85, max_frames: in
     n_points = len(xs)
 
     r_min = 0.15
+    min_x = min(xs - 0.5) - r_max
+    max_x = max(xs - 0.5) + r_max
+    min_y = min(ys - 0.5) - r_max  # Note: ys are inverted in plot
+    max_y = max(ys - 0.5) + r_max
     ring_linewidth = 4
 
     rgba_labels = mcolors.to_rgba("#FFFFFF", 0.7)
@@ -524,9 +550,10 @@ def _render_radar(puzzle: Puzzle, size: int, r_max: float = 0.85, max_frames: in
 
     # Use per-puzzle scope image keyed by puzzle.uid
     imgscope = get_scope_image(uid=puzzle.uid, size=scope_size, bgcolor=bgcolor, scope_color=scope_color)
-    fig, ax = plt.subplots(figsize=(scope_size, scope_size))    
-    ax.set_xlim(0.2, size)
-    ax.set_ylim(size, 0.2)
+    fig, ax = plt.subplots(figsize=(scope_size, scope_size))
+    ax.set_position([0.02, 0.02, 0.98, 0.98])
+    ax.set_xlim(min_x, max_x)
+    ax.set_ylim(max_y, min_y)  # Inverted for grid coordinates
 
     if show_ticks:
         ax.set_xticks(range(1, size + 1))
@@ -573,7 +600,8 @@ def _render_radar(puzzle: Puzzle, size: int, r_max: float = 0.85, max_frames: in
     bg_ax.imshow(grad_img, aspect='auto', interpolation='bilinear')
     bg_ax.axis('off')
 
-    scope_ax = fig.add_axes([-0.075, -0.075, 1.15, 1.15], zorder=1)    
+    scope_ax = fig.add_axes([-0.1, -0.095, 1.18, 1.195], zorder=1)  
+    # scope_ax.set_position([0, 0, 1, 1]) 
     scope_ax.imshow(imgscope, aspect='auto', interpolation='lanczos')
     scope_ax.axis('off')
 
@@ -874,7 +902,7 @@ def _render_score_panel(state: GameState):
         pts = state.points_by_word.get(w.text, 0)
         if pts > 0 or state.game_mode == "too easy":
             letters_display = len(w.text)
-                # Extra = total points for the word minus its length (bonus earned)
+            # Extra = total points for the word minus its length (bonus earned)
             extra_pts = max(0, pts - letters_display)
             row_html = (
                 "<tr>"
@@ -884,8 +912,29 @@ def _render_score_panel(state: GameState):
                 "</tr>"
             )
             rows_html.append(row_html)
-    total_row_html = (f"<tr class=\"blue-background\"><td colspan='3'><h3 class=\"bold-text\">Total: {state.score}</h3></td></tr>")
+
+    # Timer calculation (initial render value)
+    now = datetime.now()
+    start = state.start_time or now
+    end = state.end_time or (now if is_game_over(state) else None)
+    elapsed = (end or now) - start
+    elapsed_seconds = int(elapsed.total_seconds())
+    mins, secs = divmod(elapsed_seconds, 60)
+    timer_str = f"{mins:02d}:{secs:02d}"
+
+    # Unique id for the timer span (use puzzle uid when available)
+    span_id = f"bw-timer-{getattr(state.puzzle, 'uid', 'default')}"
+    timer_span_html = (
+        f"<span id=\"{span_id}\" style='font-size:1rem; color:#ffffff;'>&nbsp;⏱ {timer_str}</span>"
+    )
+
+    total_row_html = (
+        f"<tr class=\"blue-background\"><td colspan='3'>"
+        f"<h3 class=\"bold-text\">Total: {state.score} {timer_span_html}</h3>"
+        f"</td></tr>"
+    )
     rows_html.append(total_row_html)
+
     table_html = (
         "<table class='shiny-border' style=\"background: linear-gradient(-45deg, #a1a1a1, #ffffff, #a1a1a1, #666666); width:100%; margin: 0 auto;border-collapse:separate; border-spacing:0;\">"
         f"{''.join(rows_html)}"
@@ -893,9 +942,68 @@ def _render_score_panel(state: GameState):
     )
     st.markdown(f"<div class='bw-score-panel-container'>{table_html}</div>", unsafe_allow_html=True)
 
+    # Inject client-side timer updater script so only the timer text updates
+    start_ms = int(start.timestamp() * 1000)
+    end_ms = int(end.timestamp() * 1000) if end else None
+    js = f"""
+    <script>
+    (function() {{
+      try {{
+        window.bwTimers = window.bwTimers || {{}};
+        var key = "{span_id}";
+        if (window.bwTimers[key]) {{
+          clearInterval(window.bwTimers[key]);
+        }}
+        var span = document.getElementById("{span_id}");
+        if (!span) return;
+
+        var startMs = {start_ms};
+        var endMs = {"null" if end_ms is None else end_ms};
+
+        function fmt(ms) {{
+          var total = Math.max(0, Math.floor(ms / 1000));
+          var m = Math.floor(total / 60);
+          var s = total % 60;
+          return (m < 10 ? "0" : "") + m + ":" + (s < 10 ? "0" : "") + s;
+        }}
+
+        function tick() {{
+          var now = Date.now();
+          var t = (endMs !== null ? endMs : now) - startMs;
+          span.textContent = "⏱ " + fmt(t);
+          if (endMs !== null) {{
+            clearInterval(window.bwTimers[key]);
+          }}
+        }}
+
+        tick();
+        if (endMs === null) {{
+          window.bwTimers[key] = setInterval(tick, 1000);
+        }}
+      }} catch (e) {{
+        // no-op
+      }}
+    }})();
+    </script>
+    """
+    st.markdown(js, unsafe_allow_html=True)
+
 # -------------------- Game Over Dialog --------------------
 
 def _game_over_content(state: GameState) -> None:
+    # Set end_time if not already set
+    if state.end_time is None:
+        st.session_state.end_time = datetime.now()
+        state.end_time = st.session_state.end_time
+
+    # Timer calculation
+    start = state.start_time or state.end_time or datetime.now()
+    end = state.end_time or datetime.now()
+    elapsed = end - start
+    elapsed_seconds = int(elapsed.total_seconds())
+    mins, secs = divmod(elapsed_seconds, 60)
+    timer_str = f"{mins:02d}:{secs:02d}"
+
     # Build table body HTML for dialog content
     word_rows = []
     for w in state.puzzle.words:
@@ -913,7 +1021,7 @@ def _game_over_content(state: GameState) -> None:
         "<th scope=\"col\">Extra</th>"
         "</tr></thead>"
         f"<tbody>{''.join(word_rows)}"
-        f"<tr><td colspan=\"3\"><h5 class=\"m-2\">Total: {state.score}</h5></td></tr>"
+        f"<tr><td colspan=\"3\"><h5 class=\"m-2\">Total: {state.score} <span style='font-size:1rem; color:#1d64c8;'>&nbsp;⏱ {timer_str}</span></h5></td></tr>"
         "</tbody>"
         "</table>"
     )
@@ -957,6 +1065,7 @@ def _game_over_content(state: GameState) -> None:
         <div class=\"bw-dialog-container shiny-border\">
           <div class=\"p-3 pt-2\">\n            <div class=\"mb-2\">Congratulations!</div>
             <div class=\"mb-2\">Final score: <strong class=\"text-success\">{state.score}</strong></div>
+            <div class=\"mb-2\">Time: <strong>{timer_str}</strong></div>
             <div class=\"mb-2\">Tier: <strong>{compute_tier(state.score)}</strong></div>
             <div class=\"mb-2\">Game Mode: <strong>{state.game_mode}</strong></div>
             <div class=\"mb-2\">Wordlist: <strong>{st.session_state.get('selected_wordlist', '')}</strong></div>