Enhance UI with modal overlays and improve UX

Updated `README.md` to reflect version `0.2.0` and document new features, including a loading screen and a congratulations screen for the final score and tier.

Replaced `st.expander`-based layouts in `_render_score_panel` and `_render_game_over` with HTML-based tables and modals for better styling, readability, and layout control. Added a modal overlay for the game-over screen with a detailed score summary, close button, and "New Game" button.

Introduced query parameter handling in `run_app` to allow dismissal of the game-over overlay, persisting the state in `st.session_state`.

Improved session state handling, fixed minor HTML inconsistencies, and enhanced the overall appearance and user experience.

README.md

@@ -104,52 +104,39 @@ docker run -p 8501:8501 battlewords
 4. **The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.**
 
 ## Changelog
-- 0.1.12
-  - Updated the version to 0.1.12. Added new CSS classes `.bold-text` and `.blue-background` for improved text and background styling. Modified `.shiny-border` to adjust padding and border-radius for a more polished appearance.
-  - Refactored `_render_score_panel` to replace the `st.expander`-based layout with an HTML-based table, introducing independent column backgrounds, visible gaps, and a new "extra points" calculation. Added a total row with enhanced styling.
-  - Reorganized `run_app` for better layout structure and removed redundant state assignment.
+- 0.2.0
+  - Added a loading screen when starting a new game.
+  - Added a congratulations screen with your final score and tier when the game ends.
   
+- 0.1.13 
+  - Improved score summary layout for clarity and style.
+
+- 0.1.12
+  - Improved score summary layout and styling.
+  - Enhanced overall appearance and readability.
+
 - 0.1.11
-  - Added game-ending condition: the game now ends when all six words are guessed or all word letters are revealed.
-  - implemented word spacing logic to prevent adjacent partial words and allow for future enhancements like overlaps.
-  - implement loading html overlay and hide grid until ready.
-  - Update to Game Summary table: shows words, base points, bonus points, total score; styled with Streamlit's `st.table`.
-  - Show Grid Ticks and Space between words are now in settings.
-  - Increase default font size for better readability.
-  - Game end now modifies the grid display to show all words and disables further interaction. 
-  - Update to model for future enhancements
-  
+  - Game now ends when all words are found or revealed.
+  - Added word spacing logic and improved settings.
+
 - 0.1.10
-  - Sidebar Game Mode selector: `standard` (allows guess chaining after correct guesses) and `too easy` (no chaining; score panel reveals words list).
-  - Replaced Hit/Miss with Correct/Try Again status indicator for guesses.
-  - UI polish: animated ocean background; metal-scope styled radar retained with session-cached GIF.
-  - Footer shows version info (commit, Python, Streamlit).
-  - Word list handling: defaults to `classic.txt` when present; selection persists across new games; sort action rewrites the file and restarts after 5s notice.
-  - Documentation updated.
-  - fixed wordlist selection persistence bug
+  - Added game mode selector and improved UI feedback.
 
 - 0.1.9
-  - Background naming cleanup and consistency.
-  - Version info surfaced in Settings panel.
-  - Mobile layout improvements.
+  - Improved background and mobile layout.
 
 - 0.1.8
-  - Bumped runtime to Python 3.12 (and config/docs updated accordingly).
+  - Updated to Python 3.12.
 
 - 0.1.5
-  - Hit/Miss circular indicator.
-  - Completed words render as non-interactive styled cells.
-  - Tooltips show cell coordinates for buttons and revealed cells.
-  - Stable letter map rebuild after reveals.
+  - Added hit/miss indicator and improved grid feedback.
 
 - 0.1.4
-  - Radar rewritten as an animated GIF with metallic gradient background and scope overlay.
-  - Session-level caching of the generated radar GIF to avoid regeneration during a session.
-  - Mobile layout improvements: radar above grid on small screens; tighter grid gaps and horizontal scrolling per row.
+  - Radar visualization improved and mobile layout enhanced.
 
 - 0.1.3
-  - Sidebar wordlist picker and `Sort Wordlist` action (length-first then alphabetic) with a 5-second feedback delay before restarting a new game.
-  - Score panel improvements, per-word points, and emphasized final score styling.
+  - Added wordlist picker and sort feature.
+  - Improved score panel and final score display.
 
 ## Known Issues / TODO
 

battlewords/__init__.py

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

battlewords/ui.py

@@ -834,12 +834,8 @@ def _render_guess_form(state: GameState):
 
 
 def _render_score_panel(state: GameState):
-    # col1, col2 = st.columns([1, 3])
-    # with col1:
-    #     st.metric("Score", state.score)
-    # with col2:
-    #     st.markdown(f"Last action: {state.last_action}")
-    if is_game_over(state):
+    # Only show modal from here if game is over AND overlay wasn't dismissed
+    if is_game_over(state) and not st.session_state.get("hide_gameover_overlay", False):
         _render_game_over(state)
     else:
         # Build a simple table with independent column backgrounds and visible gaps
@@ -863,9 +859,9 @@ def _render_score_panel(state: GameState):
                 extra_pts = max(0, pts - letters_display)
                 row_html = (
                     "<tr>"
-                    f"<td class=\"blue-background \">{word_display}</td>"
-                    f"<td class=\"blue-background \">{letters_display}</td>"
-                    f"<td class=\"blue-background \">{extra_pts}</td>"
+                    f"<td class=\"blue-background \"'>{word_display}</td>"
+                    f"<td class=\"blue-background \"'>{letters_display}</td>"
+                    f"<td class=\"blue-background \"'>{extra_pts}</td>"
                     "</tr>"
                 )
                 rows_html.append(row_html)
@@ -881,33 +877,44 @@ def _render_score_panel(state: GameState):
 
 
 def _render_game_over(state: GameState):
-    st.subheader("Game Over")
-    tier = compute_tier(state.score)
-    # Final score in green
-    st.markdown(
-        f"<span class=\"bw-final-score\">Final score: {state.score}</span> — Tier: <strong>{tier}</strong>",
-        unsafe_allow_html=True,
+    # Prepare table rows for words
+    word_rows = []
+    for w in state.puzzle.words:
+        pts = state.points_by_word.get(w.text, 0)
+        extra_pts = max(0, pts - len(w.text))
+        word_rows.append(
+            f"<tr><td class='blue-background'>{w.text}</td><td class='blue-background'>{len(w.text)}</td><td class='blue-background'>{extra_pts}</td></tr>"
+        )
+    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;\">"
+        "<tr>"
+        "<th class='blue-background bold-text'>Word</th>"
+        "<th class='blue-background bold-text'>Letters</th>"
+        "<th class='blue-background bold-text'>Extra</th>"
+        "</tr>"
+        f"{''.join(word_rows)}"
+        f"<tr class='blue-background'><td colspan='3'><h3 class='bold-text'>Total: {state.score}</h3></td></tr>"
+        "</table>"
     )
-
-    with st.expander("Game summary", expanded=True):
-        header_cols = st.columns([2, 1, 2])
-        header_cols[0].markdown("**Word**")
-        header_cols[1].markdown("**Letters**")
-        header_cols[2].markdown("**Extra**")
-        for w in state.puzzle.words:
-            pts = state.points_by_word.get(w.text, 0)
-            word_display = w.text 
-            letters_display = str(len(w.text))
-            extra_display = f"+{pts} points"
-            row_cols = st.columns([1, 1, 1])
-            row_cols[0].markdown(f"{word_display}")
-            row_cols[1].markdown(f"{letters_display}")
-            row_cols[2].markdown(f"{extra_display}")
-        st.markdown(f"**Total**: {state.score}")
-
-    # footer version info on game over as well
+    # Overlay HTML with close link (sets ?overlay=0)
+    st.markdown(
+        f'''
+        <div id="bw-modal-overlay" style="position:fixed;top:0;left:0;width:100vw;height:100vh;z-index:9999;background:rgba(20,80,180,0.95);display:flex;flex-direction:column;justify-content:center;align-items:center;">
+            <div class="shiny-border" style="position:relative;background: linear-gradient(-45deg, #1d64c8, #ffffff, #1d64c8, #666666);padding:2rem 3rem;box-shadow:0 0 32px #1d64c8;min-width:340px;max-width:90vw; margin:8vh auto 5vh;">
+                <a href="?overlay=0" title="Close" style="position:absolute;top:12px;right:12px;display:inline-grid;place-items:center;width:40px;height:40px;border-radius:50%;background:rgba(0,0,0,0.25);color:#fff;text-decoration:none;font-size:1.6rem;font-weight:700;">&times;</a>
+                <h1 style="color:#fff;font-size:2.5rem;margin-bottom:0.5rem;">Congratulations!</h1>
+                <h2 style="color:#fff;font-size:2rem;margin-bottom:1rem;">Game Over</h2>
+                <div style="font-size:1.5rem;color:#1d64c8;margin-bottom:1rem;">Final score: <span style="color:#1d64c8;font-weight:800;">{state.score}</span></div>
+                <div style="font-size:1.2rem;color:#fff;margin-bottom:2rem;">Tier: <strong>{compute_tier(state.score)}</strong></div>
+                <div style="margin-bottom:2rem;">{table_html}</div>
+                <div style="color:#fff;opacity:0.7;font-size:1rem;margin-bottom:2rem;background:#1d64c8;text-align:center;">Thank you for playing BattleWords!</div>
+            </div>
+        </div>
+        ''', unsafe_allow_html=True)
+    st.markdown("<div style='height:32px'></div>", unsafe_allow_html=True)
+    if st.button("New Game", key="modal_new_game_btn", help="Start a new game", type="primary"):
+        _new_game()
     st.markdown(versions_html(), unsafe_allow_html=True)
-
     st.stop()
 
 
@@ -932,6 +939,19 @@ def _sort_wordlist(filename):
 
 
 def run_app():
+    # Handle overlay dismissal via query params using new API
+    try:
+        params = st.query_params
+    except Exception:
+        params = {}
+    if params.get("overlay") == "0":
+        # Clear param and remember to hide overlay this session
+        try:
+            st.query_params.clear()
+        except Exception:
+            pass
+        st.session_state["hide_gameover_overlay"] = True
+
     _init_session()
     st.markdown(ocean_background_css, unsafe_allow_html=True)
     _render_header()
@@ -956,8 +976,7 @@ def run_app():
         _render_grid(state, st.session_state.letter_map, show_grid_ticks=st.session_state.get("show_grid_ticks", True))
         st.button("New Game", width=125, on_click=_new_game, key="new_game_btn")
 
-
-    # End condition
+    # End condition (only show overlay if not dismissed)
     state = _to_state()
-    if is_game_over(state):
-        _render_game_over(state)  
+    if is_game_over(state) and not st.session_state.get("hide_gameover_overlay", False):
+        _render_game_over(state)