specs/specs.md

# Battlewords Game Requirements (specs.md)

## Overview
Battlewords is inspired by the classic Battleship game, but uses words instead of ships. The objective is to discover hidden words on a grid, earning points for strategic guessing before all letters are revealed.

## Game Board
- 12 x 12 grid.
- Six hidden words:
  - Two four-letter words
  - Two five-letter words
  - Two six-letter words
- Words are placed horizontally (left-right) or vertically (top-down), not diagonally.
- Words may touch edges or corners but do not overlap unless a future mode allows shared letters.
- Entry point is `app.py`.
- **Supports Dockerfile-based deployment for Hugging Face Spaces and other container platforms.**

## Gameplay (Common)
- Players click grid squares to reveal letters or empty spaces.
- Empty revealed squares are styled with CSS class `empty`.
- After any reveal, the app immediately reruns (`st.rerun`) to show the change.
- Use radar pulses to locate word boundaries (first and last letters).
- After revealing a letter, players may guess a word by entering it in a text box.
- Guess submission triggers an immediate rerun to reflect results.
- Only one guess per letter reveal; must uncover another letter before guessing again.
- In the default mode, a correct guess allows chaining an additional guess without another reveal.
- **The game ends when all six words are guessed or all word letters are revealed.**

## Scoring
- Each correct word guess awards points:
  - 1 point per letter in the word
  - Bonus points for each hidden letter at the time of guessing
- Score tiers:
  - Good: 34-37
  - Great: 38-41
  - Fantastic: 42+
- **Game over is triggered by either all words being guessed or all word letters being revealed.**

## POC (0.1.0) Rules
- No overlaps: words do not overlap or share letters.
- UI: basic grid, radar, and guess form.
- No keyboard interaction requirement.
- Seed is optional and not standardized.

## Beta (0.5.0) Additions
- 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).
- Deterministic seed support to reproduce puzzles (e.g., daily seed derived from date).

## Full (1.0.0) Rules
- No overlaps: words do not overlap or share letters.   
- Enhanced UX polish (animations, accessibility, themes).
- Persistence, leaderboards, and additional modes as specified in requirements.
- Deterministic daily mode and practice mode supported.

## New Features (v0.3.0)
- **Game ID Sharing:** Each puzzle generates a deterministic game ID based on the word list. Players can share URLs with `?game_id=ABC123` to challenge others with the same words.
- **Persistent Storage:** Game results and high scores are saved locally in `~/.battlewords/data/`.
- **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.28)
- **PWA Support:** App is installable as a Progressive Web App on desktop and mobile.
  - Added `service worker` and `manifest.json`.
  - Basic offline caching of static assets.
  - INSTALL_GUIDE.md added with platform-specific install steps.
  - No gameplay logic changes.

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

## UI Elements
- 12x12 grid
- Radar screen (shows last letter locations); y-axis inverted so (0,0) is top-left
- Text box for word guesses
- Score display (shows word, base points, bonus points, total score)
- Guess status indicator (Correct/Try Again)
- Game ID display and share button in game over dialog.
- High score expander in sidebar.
- Player name input in sidebar.
- Checkbox: "Show Challenge Share Links" (v0.2.27, default OFF)
  - When OFF:
    - Challenge Mode header hides the Share Challenge link
    - Game Over dialog still supports submitting/creating challenges, but does not display the generated share URL
  - Persisted in session state and preserved across "New Game"

## New Features (v0.2.27)
- Added "Show Challenge Share Links" visibility toggle for Challenge Mode sharing UI
- Purely a UI change; gameplay logic and storage behavior unchanged

## Word List
- External list at `battlewords/words/wordlist.txt`.
- Loaded by `battlewords.word_loader.load_word_list()` with caching.
- Filtered to uppercase A�Z, lengths in {4,5,6}; falls back if < 25 per length.

## Generator
- Centralized word loader.
- No duplicate word texts are selected.

## Entry Point
- The Streamlit entry point is `app.py`.
- **A `Dockerfile` can be used for containerized deployment (recommended for Hugging Face Spaces).**

## Deployment Requirements

### Basic Deployment (Offline Mode)
No special configuration needed. The app will run with all core gameplay features.  
Optional: Install as PWA from the browser menu (Add to Home Screen/Install app).

### Challenge Mode Deployment (Remote Storage)
Requires HuggingFace Hub integration for challenge sharing and leaderboards.

**Required Environment Variables:**
```bash
HF_API_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx  # or HF_TOKEN (write access required)
HF_REPO_ID=YourUsername/YourRepo       # Target HF dataset repository
SPACE_NAME=YourUsername/BattleWords    # Your HF Space name for URL generation
```

**Optional Environment Variables:**
```bash
CRYPTO_PK=                             # Reserved for future challenge signing
```

**Setup Steps:**
1. Create a HuggingFace account at https://huggingface.co
2. Create a dataset repository (e.g., `YourUsername/BattleWordsStorage`)
3. Generate an access token with `write` permissions:
   - Go to https://huggingface.co/settings/tokens
   - Click "New token"
   - Select "Write" access
   - Copy the token (starts with `hf_`)
4. Create a `.env` file in project root with the variables above
5. For Hugging Face Spaces deployment, add these as Space secrets

**Repository Structure (automatically created):**
```
HF_REPO_ID/
├── shortener.json                     # Short URL mappings (sid -> full URL)
└── games/
    └── {uid}/
        └── settings.json              # Challenge data with users array
```

**Data Privacy:**
- Challenge Mode stores: word lists, scores, times, game modes, player names
- No PII beyond optional player name (defaults to "Anonymous")
- Players control URL visibility via "Show Challenge Share Links" setting
- App functions fully offline when HF credentials not configured

**Deployment Platforms:**
- Local development: Run with `streamlit run app.py`
- Docker: Use provided `Dockerfile`
- Hugging Face Spaces: Dockerfile deployment (recommended)
- Any Python 3.10+ hosting with Streamlit support

## Copyright
BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.

## v0.2.20: Remote Storage and Shortened game_id URL

Game Sharing
- Each puzzle can be shared via a link containing a `game_id` querystring (short id / sid)
- `game_id` resolves to a settings JSON on the storage server (HF repo)
- JSON fields:
  - word_list (list of 6 uppercase words)
  - score (int), time (int seconds) [metadata only]
  - game_mode (e.g., classic, too easy)
  - grid_size (e.g., 12)
  - puzzle_options (e.g., { spacer, may_overlap })
- On load with `game_id`, fetch and apply: word_list, game_mode, grid_size, puzzle_options

High Scores
- Repository maintains `highscores/highscores.json` for top scores
- Local highscores remain supported for offline use

UI/UX
- Show the current `game_id` (sid) and a �Share Challenge� link
- When loading with a `game_id`, indicate the puzzle is a shared challenge

Security/Privacy
- Only game configuration and scores are stored; no personal data is required
- `game_id` is a short reference; full URL is stored in a repo JSON shortener index

## Challenge Mode & Leaderboard

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