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.

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

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

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