Add word difficulty and UI/UX improvements

- Updated to version 0.2.24 with changelog in README.md.
- Introduced `compute_word_difficulties` in `word_loader.py`.
- Enhanced `game_storage.py` to calculate and store word difficulty.
- Improved `ui.py` with compact layout, better tooltips, and
leaderboard updates to display word difficulty.
- Refactored "Share Your Challenge" for better usability.
- Updated `requirements.md` and `specs.md` to document new features.
- Enhanced Challenge Mode with difficulty display in leaderboard.

README.md

@@ -120,6 +120,13 @@ docker run -p8501:8501 battlewords
  - High Scores: local leaderboard tracking top scores by wordlist and game mode.
  - Persistent Storage: all game results saved locally for personal statistics without accounts.
  - Challenge Mode: remote storage of challenge results, multi-user leaderboard, and shareable links.
+ 
+-0.2.24
+ - compress height
+ - change incorrect guess tooltip location
+ - update final screen layout
+ - add word difficulty formula
+ - update documentation
 
 -0.2.23
  - Update miss and correct guess sound effects to new versions

battlewords/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "0.2.23"
+__version__ = "0.2.24"
 __all__ = ["models", "generator", "logic", "ui", "game_storage"]

battlewords/game_storage.py

@@ -24,6 +24,7 @@ from battlewords.modules import (
 )
 from battlewords.modules.storage import _get_json_from_repo
 from battlewords.local_storage import save_json_to_file
+from battlewords.word_loader import compute_word_difficulties
 
 # Configure logging
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
@@ -83,30 +84,44 @@ def serialize_game_settings(
     if challenge_id is None:
         challenge_id = generate_uid()
 
-    # Create user result entry with their own uid and word_list
+    # Try compute difficulty using the source file; optional
+    difficulty_value: Optional[float] = None
+    try:
+        if wordlist_source:
+            words_dir = os.path.join(os.path.dirname(__file__), "words")
+            wordlist_path = os.path.join(words_dir, wordlist_source)
+            if os.path.exists(wordlist_path):
+                total_diff, _ = compute_word_difficulties(wordlist_path, words_array=word_list)
+                difficulty_value = float(total_diff)
+    except Exception as _e:
+        # optional field, swallow errors
+        difficulty_value = None
+
+    # Build user result with desired ordering: uid, username, word_list, word_list_difficulty, score, time, timestamp
     user_result = {
-        "uid": generate_uid(),  # Unique ID for this user's game
+        "uid": generate_uid(),
         "username": username,
-        "word_list": word_list,  # Words THIS user played
-        "score": score,
-        "time": time_seconds,
-        "timestamp": datetime.now(timezone.utc).isoformat()
+        "word_list": word_list,
     }
+    if difficulty_value is not None:
+        user_result["word_list_difficulty"] = difficulty_value
+    user_result["score"] = score
+    user_result["time"] = time_seconds
+    user_result["timestamp"] = datetime.now(timezone.utc).isoformat()
 
     settings = {
-        "challenge_id": challenge_id,  # ID for the challenge itself
+        "challenge_id": challenge_id,
         "game_mode": game_mode,
         "grid_size": grid_size,
         "puzzle_options": {
             "spacer": spacer,
             "may_overlap": may_overlap
         },
-        "users": [user_result],  # Array of user results
+        "users": [user_result],
         "created_at": datetime.now(timezone.utc).isoformat(),
         "version": __version__
     }
 
-    # Add wordlist_source if provided
     if wordlist_source:
         settings["wordlist_source"] = wordlist_source
 
@@ -148,15 +163,30 @@ def add_user_result_to_game(
             logger.error(f"❌ Challenge not found: {sid}")
             return False
 
-        # Create new user result with their own uid and word_list
+        # Compute optional difficulty using the saved wordlist_source if available
+        difficulty_value: Optional[float] = None
+        try:
+            wordlist_source = settings.get("wordlist_source")
+            if wordlist_source:
+                words_dir = os.path.join(os.path.dirname(__file__), "words")
+                wordlist_path = os.path.join(words_dir, wordlist_source)
+                if os.path.exists(wordlist_path):
+                    total_diff, _ = compute_word_difficulties(wordlist_path, words_array=word_list)
+                    difficulty_value = float(total_diff)
+        except Exception:
+            difficulty_value = None
+
+        # Create new user result with ordering and optional difficulty
         user_result = {
-            "uid": generate_uid(),  # Unique ID for this user's game
+            "uid": generate_uid(),
             "username": username,
-            "word_list": word_list,  # Words THIS user played
-            "score": score,
-            "time": time_seconds,
-            "timestamp": datetime.now(timezone.utc).isoformat()
+            "word_list": word_list,
         }
+        if difficulty_value is not None:
+            user_result["word_list_difficulty"] = difficulty_value
+        user_result["score"] = score
+        user_result["time"] = time_seconds
+        user_result["timestamp"] = datetime.now(timezone.utc).isoformat()
 
         # Add to users array
         if "users" not in settings:

battlewords/ui.py

@@ -17,7 +17,7 @@ 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, auto_mark_completed_words, hidden_word_display
 from .models import Coord, GameState, Puzzle
-from .word_loader import get_wordlist_files, load_word_list  # use loader directly
+from .word_loader import get_wordlist_files, load_word_list, compute_word_difficulties
 from .version_info import versions_html  # version info footer
 from .audio import (
     _get_music_dir,
@@ -219,9 +219,9 @@ def inject_styles() -> None:
             max-width: 1100px;
            }
            .stHeading {
-                margin-bottom: 0rem !important;
-                margin-top: 0rem !important;
-                font-size: 2rem !important; /* Title */
+                margin-bottom: -1.5rem !important;
+                margin-top: -1.5rem !important;
+                # font-size: 1.75rem !important; /* Title */
                 line-height: 1.1 !important;
            }
           /* Base grid cell visuals */
@@ -507,8 +507,13 @@ def _render_header():
                 users = shared_settings.get("users", [])
 
                 if users:
-                    # Sort users by score (descending), then by time (ascending)
-                    sorted_users = sorted(users, key=lambda u: (-u["score"], u["time"]))
+                    # Sort users by score (descending), then by time (ascending), then by difficulty (descending)
+                    def leaderboard_sort_key(u):
+                        # Use -score for descending, time for ascending, -difficulty for descending (default 0 if missing)
+                        diff = u.get("word_list_difficulty", 0)
+                        return (-u["score"], u["time"], -diff)
+
+                    sorted_users = sorted(users, key=leaderboard_sort_key)
                     best_user = sorted_users[0]
                     best_score = best_user["score"]
                     best_time = best_user["time"]
@@ -521,8 +526,15 @@ def _render_header():
                         u_mins, u_secs = divmod(user["time"], 60)
                         u_time_str = f"{u_mins:02d}:{u_secs:02d}"
                         medal = ["🥇", "🥈", "🥉"][i-1] if i <= 3 else f"{i}."
+                        # show optional difficulty if present
+                        diff_str = ""
+                        if "word_list_difficulty" in user:
+                            try:
+                                diff_str = f" • diff {float(user['word_list_difficulty']):.2f}"
+                            except Exception:
+                                diff_str = ""
                         leaderboard_rows.append(
-                            f"<div style='padding:0.25rem; font-size:0.85rem;'>{medal} {user['username']}: {user['score']} pts in {u_time_str}</div>"
+                            f"<div style='padding:0.25rem; font-size:0.85rem;'>{medal} {user['username']}: {user['score']} pts in {u_time_str}{diff_str}</div>"
                         )
                     leaderboard_html = "".join(leaderboard_rows)
 
@@ -572,15 +584,6 @@ def _render_header():
 
     inject_styles()
 
-    st.markdown(
-    """
-    <style>
-    /* Compact title and subheader */
-
-    </style>
-    """,
-    unsafe_allow_html=True,
-)
 def _render_sidebar():
     with st.sidebar:
         st.header("SETTINGS")        
@@ -1135,11 +1138,13 @@ def _render_guess_form(state: GameState):
     if "incorrect_guesses" not in st.session_state:
         st.session_state.incorrect_guesses = []
 
-    # Prepare tooltip text for native browser tooltip
+    # Prepare tooltip text for native browser tooltip (stack vertically)
     recent_incorrect = st.session_state.incorrect_guesses[-10:]
     if st.session_state.get("show_incorrect_guesses", True) and recent_incorrect:
         if recent_incorrect:
-            tooltip_text = "Recent incorrect guesses:\n" + "\n".join(recent_incorrect)
+            # Build a bullet list so items stack vertically inside the tooltip
+            bullets = "\n".join(f"• {g}" for g in recent_incorrect)
+            tooltip_text = "Recent incorrect guesses:\n" + bullets
         else:
             tooltip_text = "No incorrect guesses yet"
     else:
@@ -1159,9 +1164,22 @@ def _render_guess_form(state: GameState):
         .st-key-guess_input .stTooltipIcon {
             position: absolute;
             left: 0;
-            bottom: -22px;
+            bottom: -26px; /* slight nudge down so the tooltip appears below input */
             width: auto !important;
         }
+        /* Ensure tooltip content wraps and preserves newlines for vertical stacking */
+        div[data-testid="stTooltipContent"], div[role="tooltip"] {
+            white-space: pre-wrap !important;
+            text-align: left !important;
+            max-width: 320px !important;
+            line-height: 1.2;
+            margin-bottom: 25px;            
+        }
+        /* Nudge tooltip popover below the trigger when possible */
+        div[data-testid="stTooltipPopover"] {
+            margin-top: 8px !important;
+        }
+
         /* Hide the default SVG info icon */
         .st-key-guess_input .stTooltipIcon svg.icon {
             display: none !important;
@@ -1171,6 +1189,7 @@ def _render_guess_form(state: GameState):
             display: inline-flex;
             align-items: center;
             width: auto;
+            min-width: 100px;
         }
         .st-key-guess_input .stTooltipIcon .stTooltipHoverTarget::after {
             content: "incorrect guesses";
@@ -1383,6 +1402,26 @@ def _game_over_content(state: GameState) -> None:
     mins, secs = divmod(elapsed_seconds, 60)
     timer_str = f"{mins:02d}:{secs:02d}"
 
+    # Compute optional word list difficulty for current run
+    difficulty_value = None
+    try:
+        wordlist_source = st.session_state.get("selected_wordlist")
+        if wordlist_source:
+            words_dir = os.path.join(os.path.dirname(__file__), "words")
+            wordlist_path = os.path.join(words_dir, wordlist_source)
+            if os.path.exists(wordlist_path):
+                current_words = [w.text for w in state.puzzle.words]
+                total_diff, _ = compute_word_difficulties(wordlist_path, words_array=current_words)
+                difficulty_value = float(total_diff)
+    except Exception:
+        difficulty_value = None
+
+    # Render difficulty line only if we have a value
+    difficulty_html = (
+        f'<div class="mb-2">Word list difficulty: <strong>{difficulty_value:.2f}</strong></div>'
+        if difficulty_value is not None else ""
+    )
+
     # Build table body HTML for dialog content
     word_rows = []
     for w in state.puzzle.words:
@@ -1444,13 +1483,16 @@ def _game_over_content(state: GameState) -> None:
 
     st.markdown(
         f"""
-        <div class=\"bw-dialog-container shiny-border\">\n          <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>
-            <div class=\"mb-0\">{table_html}</div>
+        <div class="bw-dialog-container shiny-border">
+          <div class="p-3 pt-2">
+            <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>
+            <div class="mb-0">{table_html}</div>
+            {difficulty_html}
           </div>
         </div>
         """,
@@ -1481,115 +1523,151 @@ def _game_over_content(state: GameState) -> None:
 
     # Share Challenge Button
     st.markdown("---")
-    st.markdown("### 🎮 Share Your Challenge")
 
-    # Check if this is a shared game being completed
-    is_shared_game = st.session_state.get("loaded_game_sid") is not None
-    existing_sid = st.session_state.get("loaded_game_sid")
+    # Style the containing Streamlit block via CSS :has() using an anchor inside this container
+    with st.container():
+        st.markdown(
+            """
+            <style>
+              /* Apply the dialog background to the Streamlit block that contains our anchor */
+              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) {
+                border-radius: 1rem;
+                box-shadow: 0 0 32px #1d64c8;
+                background: linear-gradient(-45deg, #1d64c8, #ffffff, #1d64c8, #666666);
+                color: #fff;
+                padding: 16px;
+              }
+              /* Improve inner text contrast inside the styled block */
+              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) h3,
+              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) label,
+              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) p {
+                color: #fff !important;
+              }
+              /* Ensure code block is readable */
+              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) pre,
+              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) code {
+                background: rgba(0,0,0,0.25) !important;
+                color: #fff !important;
+              }
+              /* Buttons hover contrast */
+              div[data-testid="stVerticalBlock"]:has(#bw-share-anchor) button:hover {
+                filter: brightness(1.1);
+              }
+            </style>
+            <div id="bw-share-anchor"></div>
+            """,
+            unsafe_allow_html=True,
+        )
 
-    # Username input
-    if "player_username" not in st.session_state:
-        st.session_state["player_username"] = ""
+        st.markdown("### 🎮 Share Your Challenge")
 
-    username = st.text_input(
-        "Enter your name (optional)",
-        value=st.session_state.get("player_username", ""),
-        key="username_input",
-        placeholder="Anonymous"
-    )
-    if username:
-        st.session_state["player_username"] = username
-    else:
-        username = "Anonymous"
+        # Check if this is a shared game being completed
+        is_shared_game = st.session_state.get("loaded_game_sid") is not None
+        existing_sid = st.session_state.get("loaded_game_sid")
 
-    # Check if share URL already generated
-    if "share_url" not in st.session_state or st.session_state.get("share_url") is None:
-        button_text = "📊 Submit Your Result" if is_shared_game else "🔗 Generate Share Link"
+        # Username input
+        if "player_username" not in st.session_state:
+            st.session_state["player_username"] = ""
 
-        if st.button(button_text, key="generate_share_link", use_container_width=True):
-            try:
-                # Extract game data
-                word_list = [w.text for w in state.puzzle.words]
-                spacer = state.puzzle.spacer
-                may_overlap = state.puzzle.may_overlap
-                wordlist_source = st.session_state.get("selected_wordlist", "unknown")
-
-                if is_shared_game and existing_sid:
-                    # Add result to existing game
-                    success = add_user_result_to_game(
-                        sid=existing_sid,
-                        username=username,
-                        word_list=word_list,  # Each user gets different words
-                        score=state.score,
-                        time_seconds=elapsed_seconds
-                    )
+        username = st.text_input(
+            "Enter your name (optional)",
+            value=st.session_state.get("player_username", ""),
+            key="username_input",
+            placeholder="Anonymous"
+        )
+        if username:
+            st.session_state["player_username"] = username
+        else:
+            username = "Anonymous"
 
-                    if success:
-                        share_url = get_shareable_url(existing_sid)
-                        st.session_state["share_url"] = share_url
-                        st.session_state["share_sid"] = existing_sid
-                        st.success(f"✅ Result submitted for {username}!")
-                        st.rerun()
-                    else:
-                        st.error("Failed to submit result")
-                else:
-                    # Create new game
-                    challenge_id, full_url, sid = save_game_to_hf(
-                        word_list=word_list,
-                        username=username,
-                        score=state.score,
-                        time_seconds=elapsed_seconds,
-                        game_mode=state.game_mode,
-                        grid_size=state.grid_size,
-                        spacer=spacer,
-                        may_overlap=may_overlap,
-                        wordlist_source=wordlist_source
-                    )
+        # Check if share URL already generated
+        if "share_url" not in st.session_state or st.session_state.get("share_url") is None:
+            button_text = "📊 Submit Your Result" if is_shared_game else "🔗 Generate Share Link"
+
+            if st.button(button_text, key="generate_share_link", use_container_width=True):
+                try:
+                    # Extract game data
+                    word_list = [w.text for w in state.puzzle.words]
+                    spacer = state.puzzle.spacer
+                    may_overlap = state.puzzle.may_overlap
+                    wordlist_source = st.session_state.get("selected_wordlist", "unknown")
+
+                    if is_shared_game and existing_sid:
+                        # Add result to existing game
+                        success = add_user_result_to_game(
+                            sid=existing_sid,
+                            username=username,
+                            word_list=word_list,  # Each user gets different words
+                            score=state.score,
+                            time_seconds=elapsed_seconds
+                        )
 
-                    if sid:
-                        share_url = get_shareable_url(sid)
-                        st.session_state["share_url"] = share_url
-                        st.session_state["share_sid"] = sid
-                        st.rerun()
+                        if success:
+                            share_url = get_shareable_url(existing_sid)
+                            st.session_state["share_url"] = share_url
+                            st.session_state["share_sid"] = existing_sid
+                            st.success(f"✅ Result submitted for {username}!")
+                            st.rerun()
+                        else:
+                            st.error("Failed to submit result")
                     else:
-                        st.error("Failed to generate short URL")
+                        # Create new game
+                        challenge_id, full_url, sid = save_game_to_hf(
+                            word_list=word_list,
+                            username=username,
+                            score=state.score,
+                            time_seconds=elapsed_seconds,
+                            game_mode=state.game_mode,
+                            grid_size=state.grid_size,
+                            spacer=spacer,
+                            may_overlap=may_overlap,
+                            wordlist_source=wordlist_source
+                        )
 
-            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)
-
-        # Copy to clipboard button
-        components.html(
-            f"""
-            <script>
-            function copyToClipboard() {{
-                navigator.clipboard.writeText("{share_url}").then(function() {{
-                    alert("Share link copied to clipboard!");
-                }}, function(err) {{
-                    console.error('Could not copy text: ', err);
-                }});
-            }}
-            </script>
-            <button onclick="copyToClipboard()" style="
-                width: 100%;
-                padding: 0.5rem 1rem;
-                background: #1d64c8;
-                color: white;
-                border: none;
-                border-radius: 0.5rem;
-                cursor: pointer;
-                font-size: 1rem;
-                font-weight: bold;
-            ">
-                📋 Copy Link
-            </button>
-            """,
-            height=60
-        )
+                        if sid:
+                            share_url = get_shareable_url(sid)
+                            st.session_state["share_url"] = share_url
+                            st.session_state["share_sid"] = sid
+                            st.rerun()
+                        else:
+                            st.error("Failed to generate short URL")
+
+                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)
+
+            # Copy to clipboard button
+            components.html(
+                f"""
+                <script>
+                function copyToClipboard() {{
+                    navigator.clipboard.writeText("{share_url}").then(function() {{
+                        alert("Share link copied to clipboard!");
+                    }}, function(err) {{
+                        console.error('Could not copy text: ', err);
+                    }});
+                }}
+                </script>
+                <button onclick="copyToClipboard()" style="
+                    width: 100%;
+                    padding: 0.5rem 1rem;
+                    background: #1d64c8;
+                    color: white;
+                    border: none;
+                    border-radius: 0.5rem;
+                    cursor: pointer;
+                    font-size: 1rem;
+                    font-weight: bold;
+                ">
+                    📋 Copy Link
+                </button>
+                """,
+                height=60
+            )
 
     st.markdown("---")
 

battlewords/word_loader.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import re
 import os
+import string
 from typing import Dict, List, Optional
 
 import streamlit as st
@@ -128,4 +129,86 @@ def load_word_list(selected_file: Optional[str] = None) -> Dict[int, List[str]]:
     except Exception:
         # Missing file or read error
         used_source = "fallback"
-        return _finalize(FALLBACK_WORDS, used_source)
+        return _finalize(FALLBACK_WORDS, used_source)
+
+
+# Ensure this function is at module scope (not indented) and import string at top
+def compute_word_difficulties(file_path, words_array=None):
+    """
+    1. Read and sanitize word list: uppercase A–Z only, skip comments/blank lines.
+    2. Count occurrences of each letter across all words (A..Z only).
+    3. Compute frequency f_l = count / n, rarity r_l = 1 - f_l for each letter.
+    4. Count words sharing same first/last letters for each pair.
+    5. If words_array provided, use it (uppercase); else use full list.
+    6. For each word: get unique letters L_w, k = |L_w|.
+    7. Compute average rarity a_w = sum(r_l for l in L_w) / k.
+    8. Get count c_w of words with same first/last, uniqueness u_w = 1 / c_w.
+    9. Difficulty d_w = [k * (26 - k)] / [(k + 1) * (a_w + u_w)] if denominator != 0, else 0.
+    10. Return total difficulty (sum d_w) and dict of {word: d_w}.
+    """
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            raw_lines = f.readlines()
+    except Exception:
+        return 0, {}
+
+    # Sanitize lines similarly to load_word_list()
+    cleaned_words = []
+    for raw in raw_lines:
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "#" in line:
+            line = line.split("#", 1)[0].strip()
+        word = line.upper()
+        # keep only A–Z words
+        if re.fullmatch(r"[A-Z]+", word):
+            cleaned_words.append(word)
+
+    W = cleaned_words
+    n = len(W)
+    if n == 0:
+        return 0, {}
+
+    letter_counts = {l: 0 for l in string.ascii_uppercase}
+    start_end_counts = {}
+
+    for w in W:
+        letters = set(w)
+        # Only count A..Z to avoid KeyError
+        for l in letters:
+            if l in letter_counts:
+                letter_counts[l] += 1
+        first, last = w[0], w[-1]
+        key = (first, last)
+        start_end_counts[key] = start_end_counts.get(key, 0) + 1
+
+    f_l = {l: count / n for l, count in letter_counts.items()}
+    r_l = {l: 1 - f for l, f in f_l.items()}
+
+    if words_array is None:
+        words_array = W
+    else:
+        # Ensure A–Z and uppercase for the selection as well
+        words_array = [
+            w.upper()
+            for w in words_array
+            if re.fullmatch(r"[A-Z]+", w.upper())
+        ]
+
+    difficulties = {}
+    for w in words_array:
+        L_w = set(w)
+        k = len(L_w)
+        if k == 0:
+            continue
+        a_w = sum(r_l.get(l, 0) for l in L_w) / k
+        first, last = w[0], w[-1]
+        c_w = start_end_counts.get((first, last), 1)
+        u_w = 1 / c_w
+        denominator = (k + 1) * (a_w + u_w)
+        d_w = 0 if denominator == 0 else (k * (26 - k)) / denominator
+        difficulties[w] = d_w
+
+    total_difficulty = sum(difficulties.values())
+    return total_difficulty, difficulties

specs/requirements.md

@@ -129,6 +129,12 @@ Current Deltas (0.1.3 → 0.1.10)
   - Guess feedback indicator switched to Correct/Try Again.
   - Version footer shows commit/Python/Streamlit; ocean background effect.
   - Word list default/persistence fixes and sort action persists after delay.
+- 0.2.24
+ - compress height
+ - change incorrect guess tooltip location
+ - update final screen layout
+ - add word difficulty formula
+ - update documentation
 
 Known Issues / TODO
 - Word list selection bug: improper list fetched/propagated in some runs.

specs/specs.md

@@ -59,6 +59,12 @@ Battlewords is inspired by the classic Battleship game, but uses words instead o
 - **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.
 
+## New Features (v0.2.24)
+- **UI Improvements:** More compact layout, improved tooltip for incorrect guesses, and updated final score screen.
+- **Word Difficulty:** Added a word difficulty formula and display for each game/challenge, visible in the final score and leaderboard.
+- **Challenge Mode:** Enhanced leaderboard with difficulty display, improved result submission, and clearer challenge sharing.
+- **Documentation:** Updated to reflect new features and UI changes.
+
 ## 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.
@@ -118,4 +124,5 @@ Security/Privacy
 
 - When loading a shared challenge via `game_id`, the leaderboard displays all user results for that challenge.
 - **Sorting:** The leaderboard is sorted by highest score (descending), then by fastest time (ascending).
+- **Difficulty:** Each result now displays a computed word list difficulty value.
 - Results are stored remotely in a Hugging Face dataset repo and updated via the app.