Documentation Update

README.md

@@ -28,6 +28,7 @@ BattleWords is a vocabulary learning game inspired by classic Battleship mechani
 - Reveal grid cells and guess words for points
 - Scoring tiers: Good (34–37), Great (38–41), Fantastic (42+)
 - Responsive UI built with Streamlit
+- Wordlist sidebar controls (picker + one-click sort)
 - Deterministic seed support (Beta/Full)
 - Keyboard navigation and guessing (Beta/Full)
 - Overlapping words on shared letters (Beta)
@@ -85,6 +86,27 @@ streamlit run app.py
 3. Earn points for correct guesses and bonus points for unrevealed letters.
 4. **The game ends when all six words are found or all word letters are revealed. Your score tier is displayed.**
 
+## Changelog
+
+- 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.
+
+- 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.
+
+- 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.
+
+## Known Issues / TODO
+
+- Word list loading bug: the app may not select the proper word lists in some environments. Investigate `word_loader.get_wordlist_files()` / `load_word_list()` and sidebar selection persistence to ensure the chosen file is correctly used by the generator.
+
 ## Development Phases
 
 - **Proof of Concept (0.1.0):** No overlaps, basic UI, single session.

requirements.txt

@@ -3,6 +3,7 @@ pandas
 streamlit
 matplotlib
 numpy
+Pillow
 pytest
 flake8
 mypy

specs/requirements.md

@@ -3,14 +3,18 @@
 This document breaks down the tasks to build Battlewords using the game rules described in `specs.md`. It is organized in phases: a minimal Proof of Concept (POC), a Beta Version (0.5.0), and a Full Version (1.0.0).
 
 Assumptions
-- Tech stack: Python 3.10+, Streamlit for UI, matplotlib for radar, numpy for tick helpers.
+- Tech stack: Python 3.10+, Streamlit for UI, matplotlib for radar, numpy for tick helpers, Pillow for animated GIFs.
 - Single-player, local state stored in Streamlit session state for POC.
 - Grid is always 12x12 with exactly six words: two 4-letter, two 5-letter, two 6-letter words; horizontal/vertical only; no shared letters or overlaps in POC; shared-letter overlaps allowed in Beta; no overlaps in Full.
 - Entry point is `app.py`.
 
 Streamlit key components (API usage plan)
 - State & caching
-  - `st.session_state` for `puzzle`, `revealed`, `guessed`, `score`, `can_guess`, `last_action`.
+  - `st.session_state` for `puzzle`, `grid_size`, `revealed`, `guessed`, `score`, `last_action`, `can_guess`.
+  - `st.session_state.points_by_word` for per-word score breakdown.
+  - `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.
 - Layout & structure
   - `st.title`, `st.subheader`, `st.markdown` for headers/instructions.
@@ -18,12 +22,13 @@ Streamlit key components (API usage plan)
   - `st.expander` for inline help/intel tips.
 - Widgets (interaction)
   - `st.button` for each grid cell (144 total) with unique `key` to handle reveals.
-  - `st.form` + `st.text_input` + `st.form_submit_button("OK")` for controlled word guessing.
-  - `st.button("New Game")` or `st.link_button` to reset state.
-  - `st.metric` to show score; `st.checkbox`/`st.toggle` for optional settings (e.g., show radar).
+  - `st.form` + `st.text_input` + `st.form_submit_button("OK")` for controlled word guessing (disabled until a reveal).
+  - `st.button("New Game")` to reset state; sidebar `selectbox` for wordlist selection and `Sort Wordlist` button (length+alpha).
+  - `st.metric` to show score.
 - Visualization
-  - `st.pyplot` for the radar mini-grid (scatter on a 12×12 axes) or `st.plotly_chart` if interactive.
-  - Radar plot uses `ax.set_ylim(size, 0)` to invert Y so (0,0) is top-left.
+  - Animated radar using matplotlib `FuncAnimation` + `PillowWriter` saved to GIF.
+  - Scope overlay image generated once and reused; metallic gradient background.
+  - Radar plot uses inverted Y so (0,0) is top-left.
 - Control flow
   - App reruns on interaction; uses `st.rerun()` after state changes (reveal, guess); `st.stop()` after game over summary to freeze UI.
 
@@ -35,10 +40,10 @@ Folder Structure
   - `word_loader.py` – load/validate/cached word lists (uses `battlewords/words/wordlist.txt` with fallback)
   - `generator.py` – word placement; imports from `word_loader`; avoids duplicate words
   - `logic.py` – game mechanics (reveal, guess, scoring, tiers)
-  - `ui.py` – Streamlit UI composition; immediate rerender on reveal/guess via `st.rerun()`; inverted radar Y
+  - `ui.py` – Streamlit UI composition; animated radar; immediate rerender on reveal/guess via `st.rerun()`; inverted radar Y
   - `words/wordlist.txt` – candidate words
 - `specs/` – documentation (this file and `specs.md`)
-- `tests/` – unit tests (optional for now)
+- `tests/` – unit tests
 
 Phase 1: Proof of Concept (0.1.0)
 Goal: A playable, single-session game demonstrating core rules, scoring, and radar without persistence or advanced UX.
@@ -73,59 +78,61 @@ Acceptance: Generator returns a valid `Puzzle` passing validation checks (no col
 - Reveal:
   - Click a covered cell to reveal; if the cell is part of a word, show the letter; else mark empty (CSS class `empty`).
   - After a reveal action, set `can_guess=True`.
-  - Streamlit: 12×12 `st.columns` + `st.button(label, key=f"cell_{r}_{c}")` per cell; on click, update `st.session_state` and call `st.rerun()`.
 - Guess:
   - Accept a guess only if `can_guess` is True and input length ∈ {4,5,6}.
   - Match guess case-insensitively against unguessed words in puzzle.
   - If correct: add base points = word length; bonus points = count of unrevealed cells in that word at guess time; mark all cells of the word as revealed; add to `guessed`.
   - If incorrect: no points awarded.
   - After any guess, set `can_guess=False` and require another reveal before next guess.
-  - Streamlit: `with st.form("guess"):` + `st.text_input("Your guess", key="guess_text")` + `st.form_submit_button("OK", disabled=not st.session_state.can_guess)`; after guess, call `st.rerun()`.
-- **End of game when all 6 words are guessed or all word letters are revealed; display summary and tier, then `st.stop()`.**
+  - Exception in 0.1.5: after a correct guess, another guess is allowed without a reveal (`can_guess=True`).
+  - Streamlit: `with st.form("guess"):` + `st.text_input("Your guess")` + `st.form_submit_button("OK", disabled=not can_guess)`; after guess, call `st.rerun()`.
+- End of game when all 6 words are guessed or all word letters are revealed; display summary and tier, then `st.stop()`.
 
 Acceptance: Unit tests cover scoring, guess gating, and reveal behavior.
 
 5) UI (Streamlit)
 - Layout:
   - Title and brief instructions via `st.title`, `st.subheader`, `st.markdown`.
-  - Left: 12×12 grid using `st.columns(12)` of `st.button`s.
-  - Right: Radar mini-grid via `st.pyplot` (matplotlib scatter) or `st.plotly_chart`.
-  - Bottom/right: Guess form using `st.form`, `st.text_input`, `st.form_submit_button`.
-  - Score panel showing current score using `st.metric` and `st.markdown` for last action.
-  - Optional `st.sidebar` to host reset/new game and settings; shows word list source/counts.
+  - Left: 12×12 grid using `st.columns(12)`.
+  - Right: Animated radar, Hit/Miss indicator, guess form, and score panel.
+  - Sidebar: New Game, wordlist selectbox, Sort Wordlist action.
 - Visuals:
-  - Covered cell vs revealed styles: use button labels/emojis and background color hints; revealed empty cells use CSS class `empty` for background.
+  - Covered vs revealed styles; revealed empty cells use CSS class `empty`.
+  - Completed word cells styled with `bw-cell-complete`; cell tooltips show coordinates.
 
-Acceptance: Users can play end-to-end in one session; UI updates consistently; radar shows exactly 6 pulses; single-click reveal and guess update via rerun.
+Acceptance: Users can play end-to-end; radar shows exactly 6 pulses; reveal and guess update via rerun; completed words are visually distinct.
 
 6) Scoring Tiers
 - After game ends, compute tier:
   - Good: 34–37
   - Great: 38–41
   - Fantastic: 42+
-- Display final summary with found words, per-word points, total.
-- Streamlit: show results in a `st.container` or `st.expander("Game summary")`.
-
-Acceptance: Tier text shown at game end; manual test with mocked states.
 
 7) Basic Tests
-- Unit tests for:
-  - Placement validity (bounds, overlap, counts, no duplicate words).
-  - Scoring logic and bonus calculation.
-  - Guess gating (must reveal before next guess).
-
-Acceptance: Tests run and pass locally.
-
-Beta Version (0.5.0)
-Goal: Introduce overlapping words on shared letters, improve UX responsiveness and input options, and add deterministic seeding.
-
-A) Generator and Validation
-- Allow shared-letter overlaps: words may cross on the same letter; still disallow conflicting letters on the same cell.
-- Optional validation pass to detect and avoid unintended adjacent partial words (content curation rule).
-- Deterministic seed support to reproduce puzzles (e.g., daily seed derived from date).
-Acceptance:
-- Placement permits shared-letter crossings only when letters match.
-- With a fixed seed/date, the same puzzle is produced.
+- Placement validity (bounds, overlap, counts, no duplicate words).
+- Scoring logic and bonus calculation.
+- Guess gating (reveal required except chaining after correct guess).
+
+Current Deltas (0.1.3 → 0.1.5)
+- 0.1.3
+  - Sidebar wordlist select; sorting persists length-then-alpha ordering; auto new-game after 5s notice.
+  - Score panel improvements; per-word points; final score styling.
+- 0.1.4
+  - Animated radar GIF with metallic gradient and scope overlay; session reuse via `radar_gif_path`.
+  - Mobile layout improvements; tighter grid spacing and horizontal scroll per row.
+- 0.1.5
+  - Hit/Miss indicator derived from `last_action`.
+  - Completed word cells render as non-buttons with tooltips.
+  - Helper functions for scope image and stable letter map rebuild.
+
+Known Issues / TODO
+- Word list selection bug: improper list fetched/propagated in some runs.
+  - Verify `get_wordlist_files()` returns correct filenames and `selected_wordlist` persists across `_new_game()`.
+  - Ensure `load_word_list(selected_wordlist)` loads the chosen file and matches `generate_puzzle(words_by_len=...)` expected shape.
+  - Add tests for selection, sorting, and fallback behavior.
+
+Beta (0.5.0) – Planned
+- Allow shared-letter overlaps when letters match; deterministic seeding; keyboard navigation.
 
 B) UI and Interaction
 - Cell rendering with consistent sizing and responsive layout (desktop/mobile).

specs/specs.md

@@ -39,7 +39,6 @@ Battlewords is inspired by the classic Battleship game, but uses words instead o
 - Seed is optional and not standardized.
 
 ## Beta (0.5.0) Additions
-- Overlaps allowed on shared letters: words may cross only where letters match; still forbid conflicting letters in the same cell.
 - Optional validation pass to avoid unintended adjacent partial words (content curation rule).
 - Cell rendering with consistent sizing and responsive layout (desktop/mobile).
 - Keyboard support for navigation and guessing (custom JS via `st.html` or a component).