# word — word-games & word-play pack

Word-games & word-play capability pack (pure JS, zero deps, ships its own ~3.2k common-word dictionary): find anagrams and check isAnagram, compute Scrabble tile scores, play Wordle (per-position...


A self-contained pack of word games and word-play tools. Pure JS, **zero npm deps** (Node built-ins
only). Ships its own compact common-word dictionary in `data/common-words.json` (~3.2k lowercase
`a–z` words, lengths 2–9) so every dictionary-backed tool works offline and deterministically.

## What it is

Anagram finding & checking, Scrabble scoring, Wordle (feedback + candidate solving), letter
unscrambling, palindrome checks, syllable counting, suffix-heuristic rhyming, hangman word picks,
word-ladder chains, and letter counting — plus a few handy extras. It's the **word games** corner of
the ecosystem; it plays *with* words rather than transforming or analyzing text.

## Tools

| Tool | Args | Returns |
|---|---|---|
| `anagrams` | `{ word, includeSelf? }` | dictionary words that are full anagrams of `word` |
| `isAnagram` | `{ a, b }` | do `a` and `b` use exactly the same letters? |
| `scrabbleScore` | `{ word }` | Scrabble tile value + per-letter breakdown |
| `wordleFeedback` | `{ guess, answer }` | per-position `green`/`yellow`/`grey` + pattern (`GYG__`) |
| `wordleCandidates` | `{ constraints }` | dictionary words matching greens/yellows/greys/length |
| `unscramble` | `{ letters, full?, min? }` | words from a scramble (anagram, or Boggle-style sub-words) |
| `isPalindrome` | `{ word }` | same forwards & backwards? (ignores case/spaces/punct) |
| `syllableCount` | `{ word }` | heuristic English syllable count (per-word for phrases) |
| `rhymesWith` | `{ word, min?, limit? }` | suffix-heuristic rhymes, best (longest shared tail) first |
| `hangmanWord` | `{ difficulty?, seed? }` | a random word by difficulty band + masked template |
| `wordChain` | `{ start, end?, steps?, seed? }` | word ladder (one letter at a time); BFS shortest path |
| `countLetters` | `{ word \| text }` | letter frequency table + vowel/consonant tallies |
| `isWord` | `{ word }` | is `word` in the built-in dictionary? |
| `wordInfo` | `{ word }` | one-shot profile: length, syllables, score, palindrome, anagrams |
| `pangramCheck` | `{ text }` | uses every letter A–Z? reports missing letters |
| `acronym` | `{ text, stopwords? }` | acronym from first letters of each word |

### Wordle constraints (`wordleCandidates`)

```json
{
  "greens":  [{ "letter": "c", "position": 0 }],
  "yellows": [{ "letter": "r", "position": 2 }],
  "greys":   ["s", "t", "n"],
  "length":  5
}
```

Green = right letter, right spot. Yellow = right letter, wrong spot. Grey = absent (duplicate-safe:
a letter that is green/yellow elsewhere is not excluded). Results are ranked by unique-letter
frequency so the most information-rich guesses come first.

## Usage

```js
import word from './index.js';

word.adapters.anagrams({ word: 'listen' });
// { word: 'listen', count: n, anagrams: ['enlist','silent','tinsel', ...] }

word.adapters.wordleFeedback({ guess: 'crane', answer: 'cadre' });
// { pattern: 'G_Y_Y', feedback: [...], solved: false }

word.adapters.wordChain({ start: 'cold', end: 'warm' });
// { steps: n, chain: ['cold','cord','word','ward','warm'] }

word.adapters.scrabbleScore({ word: 'quiz' });
// { word: 'quiz', score: 22, breakdown: [...] }
```

Randomized tools (`hangmanWord`, `wordChain` without an `end`) accept an optional numeric `seed` for
reproducible output; omit it for `Math.random()`. Everything else is a pure function of its input.

## Dataset

`data/common-words.json` — a plain JSON array of ~3.2k lowercase `a–z` words (lengths 2–9),
sorted and deduped. Chosen for broad game usefulness (common English vocabulary), not exhaustive
coverage — so anagram/rhyme/ladder results are curated and fast rather than dictionary-complete.

## DRY boundary

- **`a-text`** owns **string transforms** — case conversion, ciphers (Caesar/ROT13/Vigenère),
  digests, base64/encoding, stemming. Reach for it to *reshape* a string.
- **`nlp`** owns **corpus analysis** — sentiment, keyword extraction, summarization, readability,
  entity extraction over documents. Reach for it to *analyze text*.
- **`word`** (here) owns **games & play over a dictionary** — anagrams, Scrabble, Wordle, rhymes,
  hangman, word ladders, syllables, letter counting.

If you're transforming a string → `a-text`. Analyzing a document → `nlp`. Playing *with* words →
you're in the right place.


---
Source: shared/engines/adapters/domain/word/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/word