# Screbbla

A web app that helps you find the highest-scoring plays in a real-world word-tile board game. You enter the board and your rack by hand; the solver finds every legal play, ranks them, and can export the position as a prompt to paste into Claude for strategy and blocking advice. It was built as "Scrabble Coach" and is now published in the Toolbox as Screbbla at `app.austinpranger.com/screbbla`.

## What it does

- **Exact move generation** for a standard 15x15 board: all legal plays, cross-words, blanks, premium squares, and the 50-point bingo bonus.
- **Calculator mode (default):** tap a square and just type tiles onto the board. The first tap types across, tapping the same square again switches to down, and typing jumps over tiles already there. Enter your rack, tap Find moves, and optionally Place on board. No scores or turns to track. Turn on **Settings > Play mode > Play-by-play** to track scores, turns and each play instead (scores are calculated automatically when you add anyone's play, with an override).
- **Equity ranking**: score plus a heuristic value for the tiles you keep (keep the S and blank, dump the Q).
- **Defense check**: for the top 12 plays, samples random opponent racks from the unseen tiles and measures their best reply, then ranks by `score + leave - weight x opponent reply`.
- **Unseen tile tracker** and bag estimate.
- **Copy for Claude**: board, rack, unseen tiles, scores and top moves as a ready-to-paste prompt.
- **Autosave and multiple games:** every change is saved to the current game in your browser. The **Games** page lets you open, rename, duplicate, delete, export and import games. "Save snapshot" on the Play screen makes a save point.
- **Import / export:** download a game or a full backup (games + settings) as JSON, copy the JSON, and restore from a file or pasted text with a preview and confirm step. Imports never overwrite unless you choose "Replace all". The word list is intentionally not part of backups.
- **Safety nets:** a loud warning when browser storage is full or blocked, automatic reload (with a notice) when another tab changes or deletes the open game, and unreadable saved data is set aside rather than overwritten.
- **Settings page:** theme, default players for new games, how many moves to show, leave-value ranking, defense-check strength, Claude prompt size and extra instructions, word list, and backup/restore. Everything saves immediately.
- Undo is supported.

## How it fits in the Toolbox

The Toolbox serves each folder under `tools/public/` as a static site, so Screbbla is a Next.js app that is **exported to static files** and published into this folder's root:

- `next.config.mjs` sets `output: "export"`, `basePath: "/screbbla"` and `trailingSlash: true` (matching the Toolbox's `vercel.json`).
- `npm run publish-tool` runs `next build` and then `scripts/publish.mjs`, which copies `out/` into this folder (`index.html`, `games/`, `settings/`, `_next/`, `words.txt`, `404.html`). `.published.json` records what was copied so stale hashed files are removed on the next publish.
- `meta.json` and `info.md` are the Toolbox's card and write-up files. The Toolbox build copies this whole folder to `dist/screbbla/`.
- **The published files are committed.** After any change under `src/` or `public/`, run `npm run publish-tool` and commit the result, otherwise the live site won't change.
- Storage keys all start with `screbbla-` because every Toolbox tool shares one origin. Data saved under the old `scrabble-coach-*` names is moved over automatically, and exports made by the old app can still be imported.

## Run locally

```bash
npm install
npm run dev            # http://localhost:3000/screbbla
npm test               # engine, storage and UI tests
npm run typecheck
npm run build          # static export to out/
npm run publish-tool   # build + copy into this folder for the Toolbox
```

To preview exactly what the Toolbox will serve, run `npm run build` and `npm run serve` at the repo root, then open `http://localhost:4173/screbbla/`. Note that the Toolbox build copies this whole folder into `dist/`, including `node_modules` if you have installed it locally, so the local `dist/` gets large; a clean checkout on Vercel has no `node_modules` there.

## Deploying

There is nothing separate to deploy. Run `npm run publish-tool`, commit the changes in `tools/public/screbbla/`, and push; the Toolbox's Vercel project rebuilds and serves it at `/screbbla`. See the repo root `README.md` for the Vercel and domain setup.

## Word list (important)

`public/words.txt` is a **placeholder** (the public-domain ENABLE list). It is older than the Official Scrabble Players Dictionary and is missing newer words such as QI, ZA, EW, and OK.

To match your family's dictionary exactly, supply a word list based on OSPD7 (one word per line, any case):

- replace `public/words.txt`, run `npm run publish-tool` and push, **or**
- use **Settings > Word list > Load word list...** in the app (stored in your browser, no redeploy needed; not included in backups).

The OSPD7 word list is copyrighted, so it isn't bundled here and must not be committed.

The word list is held in a compact trie (about 8 bytes per node). For a ~190,000-word list: about 3 MB of memory and roughly 110 ms to build on a desktop (measured with `node --expose-gc node_modules/.bin/vite-node scripts/measure-trie.mts path/to/words.txt`). The previous 26-way table needed about 52 MB (82 MB while growing) for the same list.

## Saving between sessions

Games live in your browser's localStorage, so they persist between visits on the same device and browser, but not across devices. To move a game to another device or keep a backup, use **Games > Export** (or **Settings > Export backup**), then **Import** on the other device. If your phone doesn't save the downloaded file, use **Copy JSON** / **Copy backup JSON** and paste it into the Import box. Clearing site data or using a private window will erase saves, so export before you do that.

## Using it at the table

- **Type tiles (calculator mode):** tap a square (the arrow shows the direction), type letters, Backspace to remove, `?` for a blank, tap the same square to flip across/down.
- **Add a play (play-by-play mode):** type `8H HELLO` for across starting at row 8, column H, or `H8 HELLO` for down. Include letters already on the board. Use lowercase for blank tiles (`HeLLO`).
- **Fix a mistake:** tap a square and retype or Backspace, or press Undo.
- **Your turn:** type your rack (`?` = blank), tap **Find moves**, tap a play to preview it on the board, optionally **Check defense**, then **Play this move**. Your rack becomes your leave; type in the tiles you draw.
- **Strategy help:** tap **Copy for Claude** and paste into a chat.

## Known limitations / ideas

- No exchange, pass, or endgame solver yet (the leave heuristic is switched off when the bag is empty).
- Leave values are static heuristics, not a Monte Carlo simulation.
- Defense uses a small random sample of opponent racks; it's a noisy estimate, not exact.
- Every autosave rewrites all saved games in one localStorage entry, which is fine for dozens of games but would need a storage change (with a migration) for hundreds.
- Possible next steps: photo/OCR board entry, optional in-app Claude API call, endgame solver, challenge/phony tracking.

## For Claude Code

See `CLAUDE.md` for project conventions and `HANDOFF_PROMPT.md` for the original handoff prompt (historical).
