specs/basic.mdx

# Battlewords: Basic Branch Requirements

**Current Version:** 0.2.44 BASIC
**Branch:** `basic`
**Last Updated:** 2026-05-21

This document defines the “basic” version scope for Battlewords on the `basic` branch. It intentionally limits features to a minimal, default-settings single-player experience.

## Tech Stack
- Python 3.10+
- Streamlit (UI)
- matplotlib (radar)
- numpy (tick helpers)
- Pillow (GIF writer)

## In Scope

### Default gameplay only
- The game uses **default settings**.
- No user-configurable options are required.
- State remains local (Streamlit session state) as implemented in the core app flow.

### UI
- A single play experience accessible from `app.py`.
- Core UI elements required to play:
  - 12×12 grid
  - Reveal action
  - Guess form
  - Score display
  - Game over summary

### Layout constraints
- No footer navigation.
- No sidebar.

## Out of Scope (Basic Branch)

### Settings page
- The app **does not need** a settings page.
- No query-param routing to a settings page is required.
- Any settings-related UI should be omitted/disabled in this branch.

### Leaderboard
- The app **does not require** a full-featured leaderboard. However, a minimal "Hall of Legends" view is allowed as a small exception to the "no leaderboard" rule.
  - The Hall of Legends MUST only store runs that achieve the Legendary tier (score >= 46).
  - Hall of Legends storage MUST use existing HF-backed storage patterns and a Wrdler-compatible JSON schema, as described in the requirements document.
  - The Hall of Legends page MUST be accessible in development and production via `?page=hall`.
  - The Hall page should remain simple and may be unlinked from primary game controls.
  - No sidebar, no footer navigation, and no authentication for Hall of Legends.

### AI generation of wordlists
- The basic branch does **not** include AI-generated wordlists or HF-model-backed word generation.
- Related AI model configuration (for example `AI_MODELS`, `USE_HF_WORDS`, `HF_WORD_LIST_REPO_ID`) should be removed/unused in this branch.

### Audio (music + sound effects)
- The basic branch does **not** include background music or sound effects.
- Audio mounting via `component.html` and any audio assets/modules should be removed/unused in this branch.

### Tests
- The basic branch does **not** include tests or a `tests` folder.

## Notes
- Feature work for Settings/Leaderboard should live on non-`basic` branches.

## Basic Functions Kept

The following functions are retained in the basic branch:
- Game initialization and puzzle generation
- Word list loading and validation
- Reveal cell action
- Guess word action
- Score calculation and tier assignment
- Radar visualization
- Game over summary display

## UI Transitions and Effects

The basic branch uses:
- `CustomSpinner` for smooth loading and transition effects (New Game, initial load, Game Over/Congratulations popups).
- Streamlit CSS, markup, and `component.html` for UI styling and transition overlays.


## Codebase Constraints (Basic Branch)

### Navigation / routing
- No query-param navigation to non-game pages, except Hall of Legends.
- Remove/disable any routing paths such as `?page=settings` and `?page=leaderboard`.
- The basic branch should render the play experience and `?page=hall`.

### Word list sources
- Word lists must be loaded from local files in `battlewords/words/`.
- Do not fetch or generate word lists via Hugging Face models or other AI inference.

### Component usage
- `component.html` is allowed for UI transitions/effects (spinners, scroll-to-anchor, overlays).
- `component.html` must not be used for audio mounting in the basic branch.

## Implementation Checklist

- App starts with no errors.
- New Game transition remains smooth (uses `CustomSpinner`).
- Core gameplay works end-to-end (reveal, guess, scoring, radar, game over).
- Game Over / Congratulations popup behaves correctly and remains smooth.
- Challenge mode / share links / remote storage are removed.
- PWA support is removed.
- No audio playback occurs (no background music, no sound effects).
- No AI/HF-model-backed word list generation occurs (local wordlists only).
- Hall of Legends is reachable via `?page=hall` in development and production.
- No settings/leaderboard pages are reachable (`?page=settings` / `?page=leaderboard` disabled).
- No footer navigation and no sidebar are rendered.



Initial Proposed Prompt:

```text
You are working in the basic branch. Follow .github/copilot-instructions.md (minimal changes, preserve functionality, clear concise comments, no tests unless asked). Also follow basic.mdx requirements.
Goal: simplify the codebase to match the basic version.
Must keep:
•	Core gameplay (grid reveal, guessing, scoring, radar, game over)
•	CustomSpinner and CSS/markup/components.html usage for smooth transitions (initial load, New Game, Game Over popup)
•	Challenge mode / share links / Remote Storage (HF) feature
•	PWA support (service worker / manifest integration)
Must remove/disable from the basic codebase:
•	AI generation of wordlists / HF-model-backed word generation (remove or make unused AI_MODELS, USE_HF_WORDS, HF_WORD_LIST_REPO_ID and any related code paths)
•	Audio system (no background music, no sound effects; remove imports/usage of audio.py, audio assets, and any audio mounting via components.html)
Additional constraints:
•	No footer and no sidebar in the UI.
•	No query-param navigation for ?page=settings or ?page=leaderboard; basic should only render the play experience.
•	Word lists must load only from local files in battlewords/words/.
Deliverable:
•	Make the smallest set of code changes across the repo to enforce the above.
•	Update app.py / ui.py routing accordingly.
•	Remove now-unused modules/files only if they are truly unused after edits.
•	Summarize exactly which files you changed and why.
•	Validate the result against the "Implementation Checklist" section in this document.
```