specs/requirements.md

# Battlewords: Implementation Requirements

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, 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, 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.session_state.show_incorrect_guesses toggle.
  • st.session_state.show_challenge_share_links toggle (v0.2.27, default OFF) to control visibility of challenge share links in the header and Game Over dialog.

• Layout & structure

  • st.title, st.subheader, st.markdown for headers/instructions.
  • st.columns(12) to render the 12×12 grid; st.container for grouping; st.sidebar for secondary controls/help.
  • 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 (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

  • 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.

Folder Structure

• app.py – Streamlit entry point
• battlewords/ – Python package
  • __init__.py
  • models.py – data models and types
  • 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; 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

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.

1. Data Models

• Define Coord(x:int, y:int).
• Define Word(text:str, start:Coord, direction:str{"H","V"}, cells:list[Coord]).
• Define Puzzle(words:list[Word], radar:list[Coord]) – radar holds last-letter coordinates.
• Define GameState(grid_size:int=12, puzzle:Puzzle, revealed:set[Coord], guessed:set[str], score:int, last_action:str, can_guess:bool).

Acceptance: Types exist and are consumed by generator/logic; simple constructors and validators.

2. Word List

• Add an English word list filtered to alphabetic uppercase, lengths in {4,5,6}.
• Ensure words contain no special characters; maintain reasonable difficulty.
• Streamlit: st.cache_data to memoize loading/filtering.
• Loader is centralized in word_loader.py and used by generator and UI.

Acceptance: Loading function returns lists by length with >= 25 words per length or fallback minimal lists.

3. Puzzle Generation (Placement)

• Randomly place 2×4, 2×5, 2×6 letter words on a 12×12 grid.
• Constraints (POC):
  • Horizontal (left→right) or Vertical (top→down) only.
  • No overlapping letters between different words (cells must be unique).
• Compute radar pulses as the last cell of each word.
• Retry strategy with max attempts; raise a controlled error if generation fails.

Acceptance: Generator returns a valid Puzzle passing validation checks (no collisions, in-bounds, correct counts, no duplicates).

4. Game Mechanics

• 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.
• 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.
  • Exception: in default mode a correct guess allows chaining (can_guess=True); other modes may disable chaining.
  • 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).
  • Right: Animated radar, Correct/Try Again indicator, guess form, and score panel.
  • Sidebar: New Game, wordlist selectbox, Sort Wordlist action, Game Mode selector.
• Visuals:
  • 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; 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+

7. Basic Tests

• Placement validity (bounds, overlap, counts, no duplicate words).
• Scoring logic and bonus calculation.
• Guess gating (reveal required except chaining after correct guess when enabled).

Current Deltas (0.1.3 → 0.1.10)

• 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.
• 0.1.10
  • Game Mode selector (standard, too easy); chaining allowed only in standard.
  • 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
• 0.2.28
  • Add Progressive Web App (PWA) support with service worker and manifest.json
  • Add INSTALL_GUIDE.md for PWA install instructions
  • No gameplay logic changes

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.

Phase 1.5: Storage and Sharing (0.3.0) - NEW
Goal: Add persistent storage, high scores, and game sharing capabilities.

A) Storage Module

• Create battlewords/storage.py with:
  • GameStorage class for saving/loading game results and high scores
  • GameResult and HighScoreEntry dataclasses
  • JSON-based local storage in ~/.battlewords/data/
• Update models.py to include game_id in Puzzle (based on word list)
• Update generator.py to:
  • Generate game_id from sorted word list
  • Accept optional target_words parameter for replay
• Integrate storage into game flow:
  • Save result on game completion
  • Display high scores in sidebar Acceptance:
• Game results saved to local JSON files
• High scores correctly filtered and sorted
• Game IDs generated deterministically

B) Game Sharing

• Parse game_id from query params (?game_id=ABC123)
• Generate puzzle from game_id (same words, different positions)
• "Share Challenge" button creates shareable URL
• Display game_id in UI to show shared challenges Acceptance:
• URL with game_id loads same word set
• Share button generates correct URL
• Game ID visible to players

C) High Score Display

• Sidebar expander for high scores
• Filter by: All-time, Current Wordlist, Current Mode
• Top 10 entries with: Rank, Player, Score, Tier, Time
• Player name input (optional, defaults to "Anonymous") Acceptance:
• High scores display correctly
• Filters work as expected
• Player names saved with results

D) Tests

• Unit tests for storage operations
• Test game ID generation consistency
• Test save/load result flow
• Test high score filtering and ranking

Milestones and Estimates (High-level)

• Phase 1 (POC): 2–4 days ✅ COMPLETE
• Phase 1.5 (Local Storage & Sharing - planned): 2–3 days ⏳ PENDING (deferred to v0.3.0)
• Phase 1.6 (Remote Storage & Challenge Mode): 3–4 days ✅ COMPLETE (v0.2.20-0.2.27)
• Phase 1.7 (Local Player History): 2–3 days ⏳ IN PROGRESS (v0.3.0)
• Beta (0.5.0): 3–5 days (overlaps, responsive UI, keyboard, deterministic seed)
• Phase 2 (Full): 1–2 weeks depending on features selected

Definitions of Done (per task)

• Code merged with tests and docs updated.
• No regressions in existing tests; coverage maintained or improved for core logic.
• Manual playthrough validates rules: reveal/guess gating, scoring, radar pulses, end state and tiers.

v0.2.20 Update: Game Sharing with Shortened game_id URL

Game Sharing Feature

• On game completion, save a JSON file to the storage server named by a unique uid.
• The JSON file contains: word_list, score, time, game_mode, grid_size, and puzzle options.
• Generate a shortened URL for this file; use it as the game_id in the shareable link.
• When a user loads a game with a game_id query string, fetch the JSON file and apply all settings for the session.

Implementation Notes

• The game_id is a shortened URL referencing the JSON file.
• The app applies all settings from the file for a true replay.
• No direct encoding of game data in the query string; only the reference is shared.

Phase 1.6: Remote Storage & Challenge Mode (v0.2.20-0.2.27) ✅ COMPLETE

Goal

Persist per-game settings and leaderboards on a storage server (Hugging Face Hub repo) with shortened URLs for challenge sharing.

A) Storage Server Integration ✅

• Imported modules from OpenBadge modules/storage.py:
  • upload_files_to_repo(...) to write JSON to HF_REPO_ID
  • gen_full_url(...) for shortener lookups/creation backed by shortener.json
• Created battlewords/game_storage.py wrapper with functions:
  • save_game_to_hf() - Save challenge and get short URL
  • load_game_from_sid() - Load challenge from short ID
  • add_user_result_to_game() - Append user result to existing challenge
  • get_shareable_url() - Generate shareable URLs
• Repository structure in HF dataset:
  • shortener.json - Short URL mappings
  • games/{uid}/settings.json - Per-game challenge data with users array
• Required env vars (.env): HF_API_TOKEN (or HF_TOKEN), HF_REPO_ID, SPACE_NAME

B) Sharing Link (game_id) ✅

• Shortened URL flow: gen_full_url(full_url=...) returns short id (sid)
• Shareable link format: https://<SPACE_NAME>/?game_id=<sid>
• On app load with game_id: fetch JSON, apply settings, show Challenge Mode banner

C) Challenge Mode Features ✅

• Multi-user leaderboards with score, time, and difficulty tracking
• Results sorted by: highest score → fastest time → highest difficulty
• Challenge Mode UI banner showing top 5 players
• Submit result to existing challenge or create new challenge
• Word list difficulty calculation and display
• "Show Challenge Share Links" toggle (default OFF) for URL visibility control
• Each player gets different random words from the same wordlist source

D) Dependencies ✅

• Added huggingface_hub and python-dotenv to requirements
• Module imports in ui.py:30

E) Acceptance Criteria ✅

• ✅ Completed game produces working share link with game_id sid
• ✅ Visiting link reconstructs challenge with leaderboard
• ✅ Multiple users can submit results to same challenge
• ✅ Leaderboard displays and sorts correctly
• ✅ Documentation updated with env vars and flows
• ✅ App works without HF credentials (Challenge Mode features disabled gracefully)

F) Implementation Files

• battlewords/game_storage.py - HF storage wrapper (v0.1.0)
• battlewords/modules/storage.py - Generic HF storage (v0.1.5)
• battlewords/ui.py - Challenge Mode UI integration (lines 508-601, 1588-1701)
• battlewords/generator.py - Support for target_words parameter

Phase 1.7: Local Player History (v0.3.0) ⏳ IN PROGRESS

Goal

Add local persistent storage for individual player game results and personal high scores (offline-capable, privacy-first).

A) Local Storage Module

• Create battlewords/local_storage.py with:
  • GameResult and HighScoreEntry dataclasses
  • JSON-based storage in ~/.battlewords/data/
  • Functions: save_game_result(), load_high_scores(), get_player_stats()
  • Storage location: ~/.battlewords/data/ (game_results.json, highscores.json)

B) High Score Display

• Sidebar expander for personal high scores
• Filter by: All-time, Current Wordlist, Current Mode
• Top 10 entries with: Rank, Player, Score, Tier, Time
• Player name input (optional, defaults to "Anonymous")

C) Player Statistics

• Games played, average score, best score
• Fastest completion time
• Per-player history tracking

D) Acceptance Criteria

• Local JSON files created and updated on game completion
• High scores display correctly in sidebar
• Filters work as expected
• Player names saved with results
• No cloud dependency required
• Easy data deletion (remove ~/.battlewords/data/)