Initial Scaffold

.python-version

@@ -0,0 +1 @@
+3.13

app.py

@@ -0,0 +1,10 @@
+import streamlit as st
+
+from battlewords.ui import run_app
+def main():
+    st.set_page_config(page_title="Battlewords (POC)", layout="wide")
+    run_app()
+
+
+if __name__ == "__main__":
+    main()

battlewords/__init__.py

@@ -0,0 +1 @@
+__all__ = ["models", "generator", "logic", "ui"]

battlewords/generator.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import random
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+import streamlit as st
+
+from .models import Coord, Word, Puzzle
+
+
+# Fallback minimal word pools if file missing or too small
+_FALLBACK: Dict[int, List[str]] = {
+    4: ["TREE", "BOAT", "WIND", "FROG", "LION", "MOON", "FORK", "GLOW", "GAME", "CODE"],
+    5: ["APPLE", "RIVER", "STONE", "PLANT", "MOUSE", "BOARD", "CHAIR", "SCALE", "SMILE", "CLOUD"],
+    6: ["ORANGE", "PYTHON", "STREAM", "MARKET", "FOREST", "THRIVE", "LOGGER", "BREATH", "DOMAIN", "GALAXY"],
+}
+
+
+@st.cache_data(show_spinner=False)
+def load_word_list() -> Dict[int, List[str]]:
+    """
+    Loads and filters a word list for lengths 4, 5, 6.
+    Returns a dict length->words (uppercase, A–Z only).
+    """
+    base = Path(__file__).parent / "words" / "wordlist.txt"
+    words_by_len: Dict[int, List[str]] = {4: [], 5: [], 6: []}
+    if base.exists():
+        try:
+            for line in base.read_text(encoding="utf-8").splitlines():
+                w = line.strip().upper()
+                if w.isalpha() and len(w) in (4, 5, 6):
+                    words_by_len[len(w)].append(w)
+        except Exception:
+            pass
+
+    # Ensure minimum pools; otherwise fallback
+    for L in (4, 5, 6):
+        if len(words_by_len[L]) < 500:
+            words_by_len[L] = _FALLBACK[L].copy()
+
+    return words_by_len
+
+
+def _fits_and_free(cells: List[Coord], used: set[Coord], size: int) -> bool:
+    for c in cells:
+        if not c.in_bounds(size) or c in used:
+            return False
+    return True
+
+
+def _build_cells(start: Coord, length: int, direction: str) -> List[Coord]:
+    if direction == "H":
+        return [Coord(start.x, start.y + i) for i in range(length)]
+    else:
+        return [Coord(start.x + i, start.y) for i in range(length)]
+
+
+def generate_puzzle(
+    grid_size: int = 12,
+    words_by_len: Optional[Dict[int, List[str]]] = None,
+    seed: Optional[int] = None,
+    max_attempts: int = 5000,
+) -> Puzzle:
+    """
+    Place exactly six words: 2x4, 2x5, 2x6, horizontal or vertical,
+    no cell overlaps. Radar pulses are last-letter cells.
+    """
+    rng = random.Random(seed)
+    words_by_len = words_by_len or load_word_list()
+    target_lengths = [4, 4, 5, 5, 6, 6]
+
+    used: set[Coord] = set()
+    placed: List[Word] = []
+
+    # Pre-shuffle the word pools for variety but deterministic with seed
+    pools: Dict[int, List[str]] = {L: words_by_len[L][:] for L in (4, 5, 6)}
+    for L in pools:
+        rng.shuffle(pools[L])
+
+    attempts = 0
+    for L in target_lengths:
+        placed_ok = False
+        pool = pools[L]
+        if not pool:
+            raise RuntimeError(f"No words available for length {L}")
+
+        # Try different source words and positions
+        word_try_order = pool[:]  # copy
+        rng.shuffle(word_try_order)
+
+        for cand_text in word_try_order:
+            if attempts >= max_attempts:
+                break
+            attempts += 1
+
+            # Try a variety of starts/orientations for this word
+            for _ in range(50):
+                direction = rng.choice(["H", "V"])
+                if direction == "H":
+                    row = rng.randrange(0, grid_size)
+                    col = rng.randrange(0, grid_size - L + 1)
+                else:
+                    row = rng.randrange(0, grid_size - L + 1)
+                    col = rng.randrange(0, grid_size)
+
+                cells = _build_cells(Coord(row, col), L, direction)
+                if _fits_and_free(cells, used, grid_size):
+                    w = Word(cand_text, Coord(row, col), direction)
+                    placed.append(w)
+                    used.update(cells)
+                    placed_ok = True
+                    break
+
+            if placed_ok:
+                break
+
+        if not placed_ok:
+            # Hard reset and retry whole generation if we hit a wall
+            if attempts >= max_attempts:
+                raise RuntimeError("Puzzle generation failed: max attempts reached")
+            return generate_puzzle(grid_size=grid_size, words_by_len=words_by_len, seed=rng.randrange(1 << 30))
+
+    puzzle = Puzzle(words=placed)
+    validate_puzzle(puzzle, grid_size=grid_size)
+    return puzzle
+
+
+def validate_puzzle(puzzle: Puzzle, grid_size: int = 12) -> None:
+    # Bounds and overlap checks
+    seen: set[Coord] = set()
+    counts: Dict[int, int] = {4: 0, 5: 0, 6: 0}
+    for w in puzzle.words:
+        if len(w.text) not in (4, 5, 6):
+            raise AssertionError("Word length invalid")
+        counts[len(w.text)] += 1
+        for c in w.cells:
+            if not c.in_bounds(grid_size):
+                raise AssertionError("Cell out of bounds")
+            if c in seen:
+                raise AssertionError("Overlapping words detected")
+            seen.add(c)
+        # Last cell must match radar pulse for that word
+        if w.last_cell not in puzzle.radar:
+            raise AssertionError("Radar pulse missing for last cell")
+
+    if counts[4] != 2 or counts[5] != 2 or counts[6] != 2:
+        raise AssertionError("Incorrect counts of word lengths")

battlewords/logic.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Dict, Tuple
+
+from .models import Coord, Puzzle, GameState, Word
+
+
+def build_letter_map(puzzle: Puzzle) -> Dict[Coord, str]:
+    mapping: Dict[Coord, str] = {}
+    for w in puzzle.words:
+        for idx, c in enumerate(w.cells):
+            mapping[c] = w.text[idx]
+    return mapping
+
+
+def reveal_cell(state: GameState, letter_map: Dict[Coord, str], coord: Coord) -> None:
+    if coord in state.revealed:
+        state.last_action = "Already revealed."
+        return
+    state.revealed.add(coord)
+    state.can_guess = True
+    ch = letter_map.get(coord, "�")
+    if ch == "�":
+        state.last_action = f"Revealed empty at ({coord.x+1},{coord.y+1})."
+    else:
+        state.last_action = f"Revealed '{ch}' at ({coord.x+1},{coord.y+1})."
+
+
+def guess_word(state: GameState, guess_text: str) -> Tuple[bool, int]:
+    if not state.can_guess:
+        state.last_action = "You must reveal a cell before guessing."
+        return False, 0
+    guess = (guess_text or "").strip().upper()
+    if not (len(guess) in (4, 5, 6) and guess.isalpha()):
+        state.last_action = "Guess must be A�Z and length 4, 5, or 6."
+        state.can_guess = False
+        return False, 0
+    if guess in state.guessed:
+        state.last_action = f"Already guessed {guess}."
+        state.can_guess = False
+        return False, 0
+
+    # Find matching unguessed word
+    target: Word | None = None
+    for w in state.puzzle.words:
+        if w.text == guess and w.text not in state.guessed:
+            target = w
+            break
+
+    if target is None:
+        state.last_action = f"'{guess}' is not in the puzzle."
+        state.can_guess = False
+        return False, 0
+
+    # Scoring: base = length, bonus = unrevealed cells in that word
+    unrevealed = sum(1 for c in target.cells if c not in state.revealed)
+    points = target.length + unrevealed
+    state.score += points
+    state.points_by_word[target.text] = points
+
+    # Reveal all cells of the word
+    for c in target.cells:
+        state.revealed.add(c)
+    state.guessed.add(target.text)
+
+    state.last_action = f"Correct! +{points} points for {target.text}."
+    state.can_guess = False
+    return True, points
+
+
+def is_game_over(state: GameState) -> bool:
+    return len(state.guessed) == 6
+
+
+def compute_tier(score: int) -> str:
+    if score >= 42:
+        return "Fantastic"
+    if 38 <= score <= 41:
+        return "Great"
+    if 34 <= score <= 37:
+        return "Good"
+    return "Keep practicing"

battlewords/models.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, List, Set, Dict
+
+
+Direction = Literal["H", "V"]
+
+
+@dataclass(frozen=True, order=True)
+class Coord:
+    x: int  # row, 0-based
+    y: int  # col, 0-based
+
+    def in_bounds(self, size: int) -> bool:
+        return 0 <= self.x < size and 0 <= self.y < size
+
+
+@dataclass
+class Word:
+    text: str
+    start: Coord
+    direction: Direction
+    cells: List[Coord] = field(default_factory=list)
+
+    def __post_init__(self):
+        self.text = self.text.upper()
+        if self.direction not in ("H", "V"):
+            raise ValueError("direction must be 'H' or 'V'")
+        if not self.text.isalpha():
+            raise ValueError("word must be alphabetic A�Z only")
+        # compute cells based on start and direction
+        length = len(self.text)
+        cells: List[Coord] = []
+        for i in range(length):
+            if self.direction == "H":
+                cells.append(Coord(self.start.x, self.start.y + i))
+            else:
+                cells.append(Coord(self.start.x + i, self.start.y))
+        object.__setattr__(self, "cells", cells)
+
+    @property
+    def length(self) -> int:
+        return len(self.text)
+
+    @property
+    def last_cell(self) -> Coord:
+        return self.cells[-1]
+
+
+@dataclass
+class Puzzle:
+    words: List[Word]
+    radar: List[Coord] = field(default_factory=list)
+
+    def __post_init__(self):
+        pulses = [w.last_cell for w in self.words]
+        self.radar = pulses
+
+
+@dataclass
+class GameState:
+    grid_size: int
+    puzzle: Puzzle
+    revealed: Set[Coord]
+    guessed: Set[str]
+    score: int
+    last_action: str
+    can_guess: bool
+    points_by_word: Dict[str, int] = field(default_factory=dict)

battlewords/ui.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from typing import Optional
+
+import matplotlib.pyplot as plt
+import streamlit as st
+
+from .generator import generate_puzzle, load_word_list
+from .logic import build_letter_map, reveal_cell, guess_word, is_game_over, compute_tier
+from .models import Coord, GameState, Puzzle
+
+
+def _init_session() -> None:
+    if "initialized" in st.session_state and st.session_state.initialized:
+        return
+
+    words = load_word_list()
+    puzzle = generate_puzzle(grid_size=12, words_by_len=words)
+
+    st.session_state.puzzle = puzzle
+    st.session_state.grid_size = 12
+    st.session_state.revealed = set()
+    st.session_state.guessed = set()
+    st.session_state.score = 0
+    st.session_state.last_action = "Welcome to Battlewords! Reveal a cell to begin."
+    st.session_state.can_guess = False
+    st.session_state.points_by_word = {}
+    st.session_state.letter_map = build_letter_map(puzzle)
+    st.session_state.initialized = True
+
+
+def _new_game() -> None:
+    st.session_state.clear()
+    _init_session()
+    st.rerun()
+
+
+def _to_state() -> GameState:
+    return GameState(
+        grid_size=st.session_state.grid_size,
+        puzzle=st.session_state.puzzle,
+        revealed=st.session_state.revealed,
+        guessed=st.session_state.guessed,
+        score=st.session_state.score,
+        last_action=st.session_state.last_action,
+        can_guess=st.session_state.can_guess,
+        points_by_word=st.session_state.points_by_word,
+    )
+
+
+def _sync_back(state: GameState) -> None:
+    st.session_state.revealed = state.revealed
+    st.session_state.guessed = state.guessed
+    st.session_state.score = state.score
+    st.session_state.last_action = state.last_action
+    st.session_state.can_guess = state.can_guess
+    st.session_state.points_by_word = state.points_by_word
+
+
+def _render_header():
+    st.title("Battlewords (POC)")
+    st.subheader("Reveal cells, then guess the hidden words.")
+    st.markdown(
+        "- Grid is 12×12 with 6 words (two 4-letter, two 5-letter, two 6-letter).\n"
+        "- After each reveal, you may submit one guess.\n"
+        "- Scoring: length + unrevealed letters of that word at guess time."
+    )
+
+def _render_sidebar():
+    with st.sidebar:
+        st.header("Controls")
+        st.button("New Game", use_container_width=True, on_click=_new_game)
+        st.markdown("Radar pulses show the last letter position of each hidden word.")
+
+
+def _render_radar(puzzle: Puzzle, size: int):
+    fig, ax = plt.subplots(figsize=(4, 4))
+    xs = [c.y + 1 for c in puzzle.radar]  # columns on x-axis
+    ys = [c.x + 1 for c in puzzle.radar]  # rows on y-axis
+    ax.scatter(xs, ys, c="red", s=60, marker="o")
+    ax.set_xlim(0.5, size + 0.5)
+    ax.set_ylim(0.5, size + 0.5)
+    ax.set_xticks(range(1, size + 1))
+    ax.set_yticks(range(1, size + 1))
+    ax.grid(True, which="both", linestyle="--", alpha=0.3)
+    ax.set_title("Radar")
+    st.pyplot(fig, use_container_width=True)
+    plt.close(fig)
+
+
+def _render_grid(state: GameState, letter_map):
+    size = state.grid_size
+    clicked: Optional[Coord] = None
+
+    grid_container = st.container()
+    with grid_container:
+        for r in range(size):
+            cols = st.columns(size, gap="small")
+            for c in range(size):
+                coord = Coord(r, c)
+                revealed = coord in state.revealed
+                label = letter_map.get(coord, " ") if revealed else " "
+                key = f"cell_{r}_{c}"
+                # Make revealed cells look disabled via help text; but still keep them clickable for UX feedback
+                if cols[c].button(label, key=key, help=f"({r+1},{c+1})"):
+                    clicked = coord
+
+    if clicked is not None:
+        reveal_cell(state, letter_map, clicked)
+        _sync_back(state)
+        # No need to st.rerun(); Streamlit will rerun after button click
+
+
+def _render_guess_form(state: GameState):
+    with st.form("guess_form"):
+        guess_text = st.text_input("Your guess", value="", max_chars=12)
+        submitted = st.form_submit_button("OK", disabled=not state.can_guess, use_container_width=True)
+        if submitted:
+            correct, _ = guess_word(state, guess_text)
+            _sync_back(state)
+
+
+def _render_score_panel(state: GameState):
+    col1, col2 = st.columns([1, 3])
+    with col1:
+        st.metric("Score", state.score)
+    with col2:
+        st.markdown(f"Last action: {state.last_action}")
+
+
+def _render_game_over(state: GameState):
+    st.subheader("Game Over")
+    tier = compute_tier(state.score)
+    st.markdown(f"Final score: {state.score} — Tier: **{tier}**")
+
+    with st.expander("Game summary", expanded=True):
+        for w in state.puzzle.words:
+            pts = state.points_by_word.get(w.text, 0)
+            st.markdown(f"- {w.text} ({len(w.text)}): +{pts} points")
+        st.markdown(f"**Total**: {state.score}")
+
+    st.stop()
+
+
+def run_app():
+    _init_session()
+    _render_header()
+    _render_sidebar()
+
+    state = _to_state()
+
+    left, right = st.columns([3, 1], gap="large")
+    with left:
+        _render_grid(state, st.session_state.letter_map)
+    with right:
+        _render_radar(state.puzzle, size=state.grid_size)
+        _render_score_panel(state)
+
+    st.divider()
+    _render_guess_form(state)
+
+    # End condition
+    state = _to_state()
+    if is_game_over(state):
+        _render_game_over(state)

battlewords/words/wordlist.txt

@@ -0,0 +1,551 @@
+# Optional: place a large A�Z word list here (one word per line).
+# The app falls back to built-in pools if fewer than 500 words per length are found.
+TREE
+BOAT
+WIND
+FROG
+LION
+MOON
+FORK
+GLOW
+GAME
+CODE
+APPLE
+RIVER
+STONE
+PLANT
+MOUSE
+BOARD
+CHAIR
+SCALE
+SMILE
+CLOUD
+ORANGE
+PYTHON
+STREAM
+MARKET
+FOREST
+THRIVE
+LOGGER
+BREATH
+DOMAIN
+GALAXY
+ABLE
+ACID
+AGED
+ALSO
+AREA
+ARMY
+AWAY
+BABY
+BACK
+BALL
+BAND
+BANK
+BASE
+BATH
+BEAR
+BEAT
+BEEF
+BELL
+BELT
+BEST
+BILL
+BIRD
+BLOW
+BLUE
+BOAT
+BODY
+BOMB
+BOND
+BONE
+BOOK
+BOOM
+BOOT
+BORN
+BOSS
+BOTH
+BOWL
+BULK
+BURN
+BUSH
+BUSY
+CALL
+CALM
+CAME
+CAMP
+CARD
+CARE
+CASE
+CASH
+CAST
+CELL
+CHAT
+CHEF
+CHEW
+CHIN
+CITY
+CLAY
+CLUB
+COAL
+COAT
+CODE
+COIN
+COLD
+COME
+COOK
+COOL
+COPE
+COPY
+CORE
+COST
+CREW
+CROP
+DARK
+DATA
+DATE
+DAWN
+DEAL
+DEAN
+DEAR
+DEBT
+DECK
+DEEP
+DEER
+DIAL
+DICK
+DIET
+DISC
+DISK
+DOCK
+DOES
+DONE
+DOOR
+DOWN
+DRAW
+DREW
+DROP
+DRUG
+DUAL
+DUCK
+DULL
+DUST
+DUTY
+EACH
+EARN
+EASE
+EAST
+EDGE
+ELSE
+EVEN
+EVER
+EVIL
+EXIT
+FACE
+FACT
+FAIR
+FALL
+FARM
+FAST
+FEAR
+FEED
+FEEL
+FEET
+FELL
+FELT
+FILE
+FILL
+FILM
+FIND
+FINE
+FIRE
+FIRM
+FISH
+FIVE
+FLAT
+FLOW
+FOAM
+FOOD
+FOOT
+FORD
+FORM
+FORT
+FOUR
+FREE
+FROM
+FUEL
+FULL
+FUND
+GAIN
+GAME
+GATE
+GEAR
+GENE
+GIFT
+GIRL
+GIVE
+GLAD
+GOAL
+GOAT
+GOLD
+GOLF
+GONE
+GOOD
+GRAY
+GREAT
+GRID
+GRIP
+GROW
+GULF
+HAIR
+HALF
+HALL
+HAND
+HANG
+HARD
+HARM
+HATE
+HAVE
+HEAD
+HEAR
+HEAT
+HELD
+HELL
+HELP
+HERB
+HERE
+HERO
+HIGH
+HILL
+HIRE
+HOLD
+HOLE
+HOME
+HOPE
+HOST
+HOUR
+HUGE
+HUNT
+HURT
+IDEA
+INCH
+INTO
+IRON
+ITEM
+JACK
+JANE
+JEAN
+JOHN
+JOIN
+JUMP
+JURY
+JUST
+KEEP
+KENT
+KEPT
+KICK
+KILL
+KIND
+KING
+KISS
+KNEE
+KNOW
+LACK
+LADY
+LAKE
+LAND
+LAST
+LATE
+LEAD
+LEFT
+LESS
+LIFE
+LIFT
+LIKE
+LINE
+LINK
+LIST
+LIVE
+LOAD
+LOAN
+LOCK
+LOGO
+LONG
+LOOK
+LOST
+LOVE
+LUCK
+LUNG
+MAIL
+MAIN
+MAKE
+MALE
+MANY
+MARK
+MASS
+MATE
+MATH
+MEAL
+MEAN
+MEAT
+MEET
+MENU
+MERE
+MILE
+MILK
+MIND
+MINE
+MISS
+MODE
+MOOD
+MOON
+MORE
+MOST
+MOVE
+MUCH
+MUST
+NAME
+NAVY
+NEAR
+NECK
+NEED
+NEWS
+NEXT
+NICE
+NICK
+NINE
+NOSE
+NOTE
+OBEY
+ODDS
+OILY
+ONCE
+ONLY
+ONTO
+OPEN
+ORAL
+OVER
+PACE
+PACK
+PAGE
+PAID
+PAIN
+PAIR
+PALM
+PARK
+PART
+PASS
+PAST
+PATH
+PEAK
+PICK
+PINK
+PIPE
+PLAN
+PLAY
+PLOT
+PLUG
+PLUS
+POEM
+POLE
+POOL
+POOR
+PORT
+POST
+PULL
+PURE
+PUSH
+RACE
+RAIL
+RAIN
+RANK
+RATE
+READ
+REAL
+REAR
+RELY
+RENT
+REST
+RICE
+RICH
+RIDE
+RING
+RISE
+RISK
+ROAD
+ROCK
+ROLE
+ROLL
+ROOF
+ROOM
+ROOT
+ROSE
+RULE
+RUSH
+SAFE
+SAID
+SAKE
+SALE
+SALT
+SAME
+SAND
+SAVE
+SEAL
+SEAT
+SEED
+SEEK
+SEEM
+SEEN
+SELF
+SELL
+SEND
+SENT
+SERV
+SETT
+SEXY
+SHED
+SHIP
+SHOP
+SHOT
+SHOW
+SHUT
+SICK
+SIDE
+SIGN
+SILK
+SING
+SINK
+SITE
+SIZE
+SKIN
+SLIP
+SLOW
+SNOW
+SOFT
+SOIL
+SOLD
+SOLE
+SOME
+SONG
+SOON
+SORT
+SOUL
+SPIN
+SPOT
+STAR
+STAY
+STEM
+STEP
+STOP
+SUCH
+SUIT
+SURE
+SWIM
+TAKE
+TALE
+TALK
+TALL
+TANK
+TASK
+TEAM
+TECH
+TELL
+TEND
+TERM
+TEST
+TEXT
+THAN
+THAT
+THEM
+THEN
+THEY
+THIN
+THIS
+TIME
+TINY
+TOLD
+TOLL
+TONE
+TONY
+TOOL
+TOUR
+TOWN
+TREE
+TRIP
+TRUE
+TUNE
+TURN
+TWIN
+TYPE
+UNIT
+UPON
+USED
+USER
+VARY
+VAST
+VERY
+VIEW
+VOTE
+WAGE
+WAIT
+WAKE
+WALK
+WALL
+WANT
+WARD
+WARM
+WASH
+WAVE
+WAYS
+WEAK
+WEAR
+WEEK
+WELL
+WENT
+WEST
+WHAT
+WHEN
+WHOM
+WIDE
+WIFE
+WILD
+WILL
+WIND
+WINE
+WING
+WIRE
+WISE
+WISH
+WITH
+WOOD
+WORD
+WORK
+YARD
+YARN
+YEAR
+YELL
+YOGA
+YOUNG
+YOUR
+ZERO
+ZONE
+APPLE
+RIVER
+STONE
+PLANT
+MOUSE
+BOARD
+CHAIR
+SCALE
+SMILE
+CLOUD
+ORANGE
+PYTHON
+STREAM
+MARKET
+FOREST
+THRIVE
+LOGGER
+BREATH
+DOMAIN
+GALAXY

pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "battlewords"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "streamlit>=1.49.1",
+]

requirements.txt

@@ -1,3 +1,4 @@
 altair
 pandas
-streamlit
+streamlit
+# Entry point is now app.py, not main.py

specs/history.md

@@ -0,0 +1,25 @@
+# Battlewords: History
+
+## Foundation
+- Invented in the early 1980s as "Word Battle," a paper-and-pencil grid game inspired by Battleship.
+- Used in reading classes for international students at San Diego State University.
+- In 1992, developed for submission to game agents; accepted by Technical Game Services (TGS).
+
+## Rename & Presentation
+- Renamed "Battlewords" in 1993.
+- Presented to Milton-Bradley at the New York trade show, but only as a videotaped paper prototype.
+- MB declined due to another European word game in development.
+
+## Sabotage & Similar Games
+- Turkish students reported a similar game, "The Admiral Sank," in Turkey.
+- Suspicions arose that students adapted and sold the idea, which became "Battle Words" (two words) in Europe, licensed to Hasbro International.
+- MB ultimately rejected the original Battlewords after seeing the European version.
+
+## Reboot & Digital Version
+- The European "Battle Words" faded into obscurity.
+- The original creator retained prototypes and correspondence.
+- Later collaborated with a Turkish programmer to create a Flash version of Battlewords for the website.
+- Plans to further develop the game.
+
+## Copyright
+BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.

specs/requirements.md

@@ -0,0 +1,196 @@
+# 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) and a Full Version with all features and polish.
+
+Assumptions
+- Tech stack: Python 3.10+, Streamlit for UI, standard library only for POC.
+- 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.
+
+Streamlit key components (API usage plan)
+- State & caching
+  - `st.session_state` for `puzzle`, `revealed`, `guessed`, `score`, `can_guess`, `last_action`.
+  - `st.cache_data` to load and filter the word list.
+- 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.
+  - `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).
+- Visualization
+  - `st.pyplot` for the radar mini-grid (scatter on a 12×12 axes) or `st.plotly_chart` if interactive.
+- Control flow
+  - App reruns on interaction; optionally use `st.rerun()` after state resets; `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
+  - `generator.py` – word placement and puzzle generation
+  - `logic.py` – game mechanics (reveal, guess, scoring)
+  - `ui.py` – Streamlit UI composition
+  - `words/wordlist.txt` – candidate words
+- `specs/` – documentation (existing)
+- `tests/` – unit tests
+
+Phase 1: Proof of Concept Version
+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.
+
+Acceptance: Loading function returns lists by length with >= 500 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:
+  - Horizontal (left→right) or Vertical (top→down) only.
+  - No overlapping letters.
+  - No shared letters between different words (cells must be unique; letters adjacent orthogonally are allowed).
+- 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).
+
+4) Game Mechanics
+- Reveal:
+  - Click a covered cell to reveal; if the cell is part of a word, show the letter; else mark 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 optionally `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)`.
+- End of game when all 6 words are guessed; 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.
+- Visuals:
+  - Covered cell vs revealed styles: use button labels/emojis and background color hints; if needed, small custom `st.html`/CSS for color.
+
+Acceptance: Users can play end-to-end in one session; UI updates consistently; radar shows exactly 6 pulses.
+
+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).
+  - Scoring logic and bonus calculation.
+  - Guess gating (must reveal before next guess).
+
+Acceptance: Tests run and pass locally.
+
+Phase 2: Full Version (All Features and Polish)
+Goal: Robust app with polish, persistence, test coverage, and optional advanced features.
+
+A) UX and Visual Polish
+- Cell rendering with consistent sizing and responsive layout (desktop/mobile).
+- Keyboard support for navigation and guessing (custom JS via `st.html` or a component if needed).
+- Animations for reveals and correct guesses (CSS/JS via `st.html` or component).
+- Color-blind friendly palette and accessible contrast.
+- Configurable themes (light/dark) via Streamlit theme config.
+- Streamlit: `st.tabs` for modes/help; `st.popover`/`st.expander` for tips; `st.toast`/`st.warning` for feedback.
+
+B) Game Content and Generation
+- Curated word lists by difficulty; exclude obscure/abusive words.
+- Deterministic seed support to reproduce puzzles (e.g., daily seed based on date).
+- Validation pass to ensure no unintended partial words formed adjacently (content curation rule, optional).
+- Optional generator diagnostics panel for QA using `st.expander` and `st.dataframe`.
+- Streamlit: `st.cache_data` for word lists; `st.cache_resource` if needed for heavier resources.
+
+C) Game Modes and Settings
+- Daily Puzzle mode (same seed for all players per day).
+- Practice mode (random puzzles).
+- Difficulty presets that tweak word selection (common vs. rare) but still keep 2×4, 2×5, 2×6.
+- Optional hint system with limited uses (e.g., reveal a random letter in an unguessed word) with score penalty.
+- Streamlit: mode selection via `st.radio`/`st.segmented_control`; settings via `st.sidebar` with `st.toggle`/`st.slider`.
+
+D) Persistence and Profiles
+- Save/Load local game state (browser cookie or Streamlit session + query params).
+- Cloud persistence via lightweight backend API (FastAPI) or Streamlit secrets + hosted storage for:
+  - User profiles (username only), completed puzzles, scores.
+  - Leaderboards for Daily mode.
+- Privacy notice and opt-in for storing data.
+- Streamlit: `st.text_input` for username; `st.button` to save; call backend via `requests`.
+
+E) Leaderboards and Sharing
+- Global and friends leaderboards (score and completion time if captured; note: game is strategy-first, time is optional).
+- Share result string with spoiler-free grid (similar to popular word games).
+- Streamlit: `st.table`/`st.dataframe` for leaderboards; `st.download_button` or copy-to-clipboard via `st.text_area` + `st.button`.
+
+F) Observability and Quality
+- Logging for generator failures and gameplay events (anonymized).
+- Error boundary UI with recover/retry.
+- Test suite:
+  - Unit: generator, logic, scoring, gating, radar.
+  - Property-based tests for generator (e.g., Hypothesis) to stress placement constraints.
+  - Integration tests that simulate a full game and validate scoring.
+  - Visual regression snapshots of grid/radar (optional).
+- CI/CD with linting (flake8/ruff), type checks (mypy/pyright), tests, and build.
+- Streamlit: developer toggles in an `st.expander` to simulate states; optional `st.fragment` to limit rerenders in hotspots.
+
+G) Performance
+- Optimize generator to avoid excessive retries (precompute candidate slots, shuffle deterministically).
+- Memoize derived UI state.
+- Efficient grid rendering (batch updates or delta rendering where possible in Streamlit).
+- Streamlit: consider `st.fragment` for the grid/radar to avoid full-page rerenders.
+
+H) Internationalization (Optional)
+- i18n-ready strings; language toggle.
+- Locale-specific word lists.
+- Streamlit: language toggle via `st.selectbox`.
+
+I) Security and Abuse Prevention
+- Validate all inputs (guess strings A–Z only).
+- Rate-limit backend endpoints (if any) and sanitize stored data.
+- Streamlit: enforce validation in the submit handler and sanitize displayed content with strict formatting.
+
+J) Deployment
+- Streamlit Community Cloud or containerized deployment (Dockerfile) to any cloud.
+- Environment configuration via `.env` or Streamlit secrets.
+- Streamlit: use `st.secrets` for API keys.
+
+Milestones and Estimates (High-level)
+- Phase 1 (POC): 2–4 days
+  - Models + generator + logic: 1–2 days
+  - UI + scoring + radar: 1 day
+  - Tests and polish: 0.5–1 day
+- 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.

specs/specs.md

@@ -0,0 +1,44 @@
+# 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 do not overlap or share letters.
+- Radar screen indicates the location of the last letter of each word.
+
+## Gameplay
+- Players click grid squares to reveal letters or empty spaces.
+- Blue squares turn black if empty; otherwise, a letter is revealed.
+- 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.
+- Only one guess per letter reveal; must uncover another letter before guessing again.
+
+## 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+
+
+## Strategy
+- Focus on finding word boundaries using radar.
+- Guess words with hidden letters for higher scores.
+- The game rewards strategy over speed.
+
+## UI Elements
+- 12x12 grid
+- Radar screen (shows last letter locations)
+- Text box for word guesses
+- Score display (shows word, base points, bonus points, total score)
+
+## Copyright
+BattlewordsTM. All Rights Reserved. All content, trademarks and logos are copyrighted by the owner.

tests/test_generator.py

@@ -0,0 +1,24 @@
+import unittest
+
+from battlewords.generator import generate_puzzle, validate_puzzle
+from battlewords.models import Coord
+
+
+class TestGenerator(unittest.TestCase):
+    def test_generate_valid_puzzle(self):
+        p = generate_puzzle(grid_size=12, seed=1234)
+        validate_puzzle(p, grid_size=12)
+        # Ensure 6 words and 6 radar pulses
+        self.assertEqual(len(p.words), 6)
+        self.assertEqual(len(p.radar), 6)
+        # Ensure no overlaps
+        seen = set()
+        for w in p.words:
+            for c in w.cells:
+                self.assertNotIn(c, seen)
+                seen.add(c)
+                self.assertTrue(0 <= c.x < 12 and 0 <= c.y < 12)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_logic.py

@@ -0,0 +1,55 @@
+import unittest
+
+from battlewords.logic import build_letter_map, reveal_cell, guess_word, is_game_over
+from battlewords.models import Coord, Word, Puzzle, GameState
+
+
+class TestLogic(unittest.TestCase):
+    def make_state(self):
+        w1 = Word("TREE", Coord(0, 0), "H")
+        w2 = Word("APPLE", Coord(2, 0), "H")
+        w3 = Word("ORANGE", Coord(4, 0), "H")
+        w4 = Word("WIND", Coord(0, 6), "V")
+        w5 = Word("MOUSE", Coord(0, 8), "V")
+        w6 = Word("PYTHON", Coord(0, 10), "V")
+        p = Puzzle([w1, w2, w3, w4, w5, w6])
+        state = GameState(
+            grid_size=12,
+            puzzle=p,
+            revealed=set(),
+            guessed=set(),
+            score=0,
+            last_action="",
+            can_guess=False,
+        )
+        return state, p
+
+    def test_reveal_and_guess_gating(self):
+        state, puzzle = self.make_state()
+        letter_map = build_letter_map(puzzle)
+        # Can't guess before reveal
+        ok, pts = guess_word(state, "TREE")
+        self.assertFalse(ok)
+        self.assertEqual(pts, 0)
+        # Reveal one cell then guess
+        reveal_cell(state, letter_map, Coord(0, 0))
+        self.assertTrue(state.can_guess)
+        ok, pts = guess_word(state, "TREE")
+        self.assertTrue(ok)
+        self.assertGreater(pts, 0)
+        self.assertIn("TREE", state.guessed)
+        self.assertFalse(state.can_guess)
+
+    def test_game_over(self):
+        state, puzzle = self.make_state()
+        letter_map = build_letter_map(puzzle)
+        # Guess all words after a reveal each time
+        for w in puzzle.words:
+            reveal_cell(state, letter_map, w.start)
+            ok, _ = guess_word(state, w.text)
+            self.assertTrue(ok)
+        self.assertTrue(is_game_over(state))
+
+
+if __name__ == "__main__":
+    unittest.main()