1# PuzzleTea23> Terminal-based puzzle game collection written in Go with Bubble Tea. PuzzleTea includes 15 puzzle games, deterministic daily and weekly challenges, Elo-backed difficulty targeting, SQLite save/load persistence, XP/stat progression, 365 accessible themes, mouse support, and JSONL/PDF printable export workflows.45## Primary docs67- [README](README.md): install, usage, game list, controls, persistence, build/test commands, and new-puzzle guide.8- [AGENTS](AGENTS.md): contributor validation rules and package ownership map.9- [Game interface](game/gamer.go): `game.Gamer`, `Mode`, `Spawner`, `SeededSpawner`, `EloSpawner`, cancellation-capable spawners, and Bubble Tea message contracts.10- [Runtime entry builder](gameentry/gameentry.go): validates metadata/runtime mode cohesion and builds variants, legacy modes, seeded spawners, and Elo spawners.11- [Registry](registry/registry.go): concrete built-in game composition root.12- [Catalog](catalog/catalog.go): pure metadata index for definitions, aliases, and daily mode lookup.13- [Root app model](app/model.go), [Update](app/update.go), [View](app/view.go): Bubble Tea lifecycle, navigation state, screen model routing, async generation, and game session hosting.14- [Resolve](resolve/resolve.go): game/mode/variant matching, seed normalization, and deterministic seeded game selection.15- [Session](session/session.go): save record creation, deterministic naming, imports, and difficulty metadata persistence.16- [Store](store/store.go): SQLite persistence layer.17- [Stats](stats/stats.go): profile, XP, daily streak, weekly progress, and category cards.18- [PDF export](export/pdf/): printable pack rendering.1920## Project shape2122- Module: `github.com/FelineStateMachine/puzzletea`23- Language/runtime: Go 1.24+24- TUI: `charm.land/bubbletea/v2`, `bubbles/v2`, `lipgloss/v2`25- CLI: Cobra26- Persistence: pure-Go SQLite via `modernc.org/sqlite`27- Validation commands: `just fmt`, `just lint`, and preferably `just test-short`2829## Core architecture for LLMs3031PuzzleTea separates pure puzzle metadata from concrete runtime wiring:32331. `puzzle` defines immutable metadata structs (`Definition`, `ModeDef`, `VariantDef`, `LegacyModeAlias`) and canonical name normalization.342. Each package under `games/<game>/` owns its model, generator, save/import code, help, keys, rendering helpers, modes, Elo logic, and optional print adapter.353. `gameentry.NewEntry` combines a game's metadata with runtime `game.Mode` implementations and panics early if definitions do not match runtime mode titles/descriptions, seeded flags, preset Elo support, or variant wiring.364. `registry` imports every built-in game exactly once and exposes lookup/import/help/daily APIs.375. `catalog` remains free of concrete game imports and indexes metadata for names, aliases, and daily entries.386. `app` is the Bubble Tea root model: it owns navigation/session/config/store/theme/debug state and delegates non-game screens through a smaller `screenModel` abstraction.397. Active puzzles implement `game.Gamer`, not plain `tea.Model`: `Update` returns `(game.Gamer, tea.Cmd)` so game packages stay behind the project-specific save/reset/help/title interface while still following Bubble Tea's Elm loop.4041## Bubble Tea lifecycle notes4243- Root `model.Init()` currently returns `nil`; startup state is prepared in `InitialModel` or `InitialModelWithGame`.44- Root `model.Update(msg)` first handles async completion messages, back actions, window resizing, global keys, active game forwarding, then screen-specific updates.45- Game generation and exports run through `tea.Cmd` functions so long-running work does not block the TUI; cancellable spawner interfaces are preferred when generation can take time.46- Root global keys handle quit, debug overlay, full help, reset, and escape-to-save/back behavior. Active games receive `game.HelpToggleMsg` for full-help state.47- Root `model.View()` returns a `tea.View` configured for alt-screen rendering.4849## Built-in games and modes5051- Fillomino: grow numbered regions to exact sizes. Modes: Mini 5x5, Easy 6x6, Medium 8x8, Hard 10x10, Expert 12x12.52- Hashiwokakero: connect islands with bridges. Modes: Easy/Medium/Hard across 7x7, 9x9, 11x11, 13x13.53- Hitori: shade cells to eliminate duplicates. Modes: Mini, Easy, Medium, Tricky, Hard, Expert.54- Lights Out: toggle lights until all are off. Modes: Easy, Medium, Hard, Extreme. Not printable.55- Netwalk: rotate network tiles so every computer connects to the server. Modes: Mini 5x5, Easy 7x7, Medium 9x9, Hard 11x11, Expert 13x13.56- Nonogram: fill cells to satisfy row/column hints. Modes: Mini, Pocket, Teaser, Standard, Classic, Tricky, Large, Grand, Epic, Massive.57- Nurikabe: build clue islands while keeping one connected sea. Modes: Mini, Easy, Medium, Hard, Expert.58- Ripple Effect: fill cages with sequential numbers while respecting ripple-distance constraints. Modes: Mini 5x5, Easy 6x6, Medium 7x7, Hard 8x8, Expert 9x9.59- Shikaku: divide the grid into rectangles with clue-sized areas. Modes: Mini 5x5, Easy 7x7, Medium 8x8, Hard 10x10, Expert 12x12.60- Spell Puzzle: connect letters to fill a crossword and find bonus anagrams. Modes: Beginner, Easy, Medium, Hard.61- Sudoku: classic 9x9 number-placement puzzle. Modes: Beginner, Easy, Medium, Hard, Expert, Diabolical.62- Sudoku RGB: Sudoku Ripeto-inspired 9x9 symbol puzzle where each row/column/box contains three each of three symbols. Modes: Beginner, Easy, Medium, Hard, Expert, Diabolical.63- Takuzu: binary grid with no three equal symbols in a row/column and balanced rows/columns. Modes: Beginner, Easy, Medium, Tricky, Hard, Very Hard, Extreme.64- Takuzu+: Takuzu plus fixed equality/inequality relation clues. Modes: Beginner, Easy, Medium, Tricky, Hard, Very Hard, Extreme.65- Word Search: find hidden words in a letter grid. Modes: Easy 10x10, Medium 15x15, Hard 20x20.6667## Development guidance6869- Keep game-specific rules, rendering, generator, mouse/key handling, save shape, and print adapter inside that game's package.70- Keep reusable TUI widgets in `ui`, cross-game metadata in `puzzle`/`catalog`, runtime composition in `registry`/`gameentry`, persistence in `store`/`session`, and printable pack/PDF concerns in `export`.71- New games should follow README's file pattern: `gamemode.go`, `model.go`, `export.go`, `keys.go`, `style.go`, `generator.go`, `elo.go`, `grid.go`, `help.md`, optional `print_adapter.go`, tests, and README.72- For non-generator validation, use short tests (`just test-short` or Go `-short`). Use full-length tests only for generator behavior.73- Before committing changes, run `just fmt` and `just lint`.7475## Code review summary7677The current architecture is cohesive for a large Bubble Tea puzzle collection: the `game.Gamer` interface gives active games a stable project-specific contract, `gameentry` catches metadata/runtime mismatches early, `catalog` avoids importing concrete games, and root `app.Update` cleanly routes global keys, screens, async messages, and active game updates. The main scaling risk is large root app state in `app/model.go`; the existing `screenModel` and session/export controllers are the right direction, so future work should continue moving screen-specific behavior out of the root model rather than adding more branches directly to `Update`.