@johnmorrisdotca/kumimoji 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ All notable changes to this project are written down here. The format follows
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-11-04
+
+A minor version: nothing that 1.4.0 gave is taken away except what children should not have been handed. The English list, the rules and the saved-game format are unchanged.
+
+### Changed
+
+- **The Japanese word list leaves out what is not for children** (MODULES-390). Children play this game, and the list was every kana reading of every JMdict entry. It now has the bar of Kotoba's kana lists (`scripts/children-bar.mjs` in Kotoba, which writes the list with `scripts/word-lists-ja.mjs`): a reading is out when every JMdict entry that spells it has a vulgar, X-rated, sensitive or derogatory mark on its first sense, or a first sense whose gloss names sex or the sex trade. A reading that an ordinary entry is also spelt like stays, and so does a line that another word plays: the tiles play ば and ぱ as は, so れいぷ is the line れいふ, which is also 霊符 (a charm). Of the 163,585 lines JMdict's release of 2026-11-04 gives, 1,347 are barred (110 of 3 kana, 347 of 4, 264 of 5, 626 longer), among them せっくす, ばいしゅん, ぽるの, えろい, おなに, ちくび, ふぇらちお, せいどれい, いんらん, ちんぽ and らぶほてる; the 5 words earlier lists held that JMdict no longer lists are kept, so a game kept half way still checks. The list holds **162,243** readings (163,461 in 1.4.0). A test (`src/childrenBar.test.ts`) holds the known bad readings out. The guide "Load and judge with word lists" says what is left out, in English and in Japanese.
+- **A seeded Japanese game is dealt differently**, as the list has fewer words to choose among: the same seed gives another bag. English games are unchanged, and so is the saved-game format; a kept Japanese game checks as before unless it spells one of the barred lines.
+- The Japanese list is made again from JMdict's release of 2026-11-04 (it was 2026-09-28): 129 readings join, 5 are kept that JMdict dropped.
+- The package is a little smaller: the Japanese list is 715 kB (394 kB gzipped), and the sizes in `docs/bundle-size.json` are measured again.
+
+### Added
+
+- The README opens with the package's thumbnail, and the demo carries it as its link preview (og:image) and publishes the card, a dark card and an icon on Pages at `thumbnail.png`, `thumbnail-dark.png` and `icon.png`.
+
+## [1.4.0] - 2026-11-02
+
+### Added
+
+- A table can be laid in the family's five cloths: `<kumimoji-table cloth="blue">`, `mountKumimoji(el, { cloth })` and `set({ cloth })`, the `cloth` embed parameter and Builder option, and `KUMIMOJI_CLOTHS`, `isCloth` and `clothVars` from `/ui`. The demo's header patches lay it through the page's theme.
+
+- **`checkKumimoji` gives its reason as a code and values as well as in English.** A refusal is now `{ ok: false, reason, code, values }`: `reason` is the sentence it has always been, word for word, and `code` (`"no-hand"`, `"givens-not-bag"`, `"wild-count-wrong"`, `"bag-exceeds-set"`, `"answer-not-grid"`, `"grid-not-the-bag"`, `"tiles-apart"`, `"not-a-word"` and `"grid-not-finished"`) and `values` (`{ size }` for `no-hand`, `{ word }` for `not-a-word`) let a site say it in its own language. `KUMIMOJI_CHECK_REASONS` lists every code with its English clause, `kumimojiRefusal(code, values)` makes a refusal, and the types are `KumimojiCheckCode` and `KumimojiCheckValues`. A test holds every refusal's `reason` to its code's clause filled with its values.
+
 ## [1.3.1] - 2026-10-31
 
 ### Changed
@@ -188,7 +211,9 @@ The first release.
   `@johnmorrisdotca/kumimoji/react`.
 - A static demo for GitHub Pages.
 
-[Unreleased]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.3.0...HEAD
+[Unreleased]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.3.1...v1.4.0
 [1.3.0]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.2.2...v1.3.0
 [1.2.1]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.2.0...v1.2.1
 [1.1.1]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.1.0...v1.1.1

package/NOTICE.md

@@ -31,7 +31,7 @@ SCOWL's own distribution.
 
 `src/words.ja.data.ts` is derived from JMdict, the Japanese-Multilingual
 Dictionary of the Electronic Dictionary Research and Development Group
-(https://www.edrdg.org/), release 2026-09-28: 163,461 hiragana readings of 2 to
+(https://www.edrdg.org/), release 2026-11-04: 162,243 hiragana readings of 2 to
 15 kana, each spelt in the 45 base kana the tiles show. JMdict is the property of
 the EDRDG and is used under the Creative Commons Attribution-ShareAlike 4.0
 licence, with the group's conditions: https://www.edrdg.org/edrdg/licence.html.

package/README.md

@@ -1,3 +1,5 @@
+<p align="center"><a href="https://johnmorrisdotca.github.io/kumimoji/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kumimoji/main/docs/images/thumbnail-dark.png"><img src="https://raw.githubusercontent.com/johnmorrisdotca/kumimoji/main/docs/images/thumbnail.png" alt="Kumimoji: letter tiles laid in a crossword by the package's own computer player." width="1200"></picture></a></p>
+
 <h1 align="center">Kumimoji <sub>組み文字</sub> — Crossword tile game in English and Japanese</h1>
 
 <p align="center"><strong>The crossword tile race: a word game where you build one crossword from a bag of letter tiles.</strong><br>
@@ -10,7 +12,7 @@ In English and in Japanese kana. The rules as pure, seeded TypeScript, two word
   <a href="./NOTICE.md"><img alt="Japanese word list: CC BY-SA 4.0" src="https://img.shields.io/badge/Japanese%20words-CC%20BY--SA%204.0-b5452c"></a>
   <img alt="No dependencies" src="https://img.shields.io/badge/dependencies-0-2f5d4a">
   <img alt="TypeScript" src="https://img.shields.io/badge/types-TypeScript-3178c6">
-  <a href="https://johnmorrisdotca.github.io/kumimoji/docs/api/main/index.html"><img alt="679.1 kB minified and gzipped" src="https://img.shields.io/badge/min%2Bgzip-679.1%20kB-2f5d4a"></a>
+  <a href="https://johnmorrisdotca.github.io/kumimoji/docs/api/main/index.html"><img alt="677.1 kB minified and gzipped" src="https://img.shields.io/badge/min%2Bgzip-677.1%20kB-2f5d4a"></a>
   <a href="https://www.npmjs.com/package/@johnmorrisdotca/kumimoji#provenance"><img alt="Published with npm provenance" src="https://img.shields.io/badge/npm-provenance-2f5d4a"></a>
 </p>
 
@@ -103,7 +105,7 @@ Or with nothing to install, [play a game in the demo](https://johnmorrisdotca.gi
 - **Races and daily puzzles.** A seed deals one bag, the same for everybody,
   and `checkKumimoji` checks a finished grid against it without searching.
 - **Japanese.** A word game that plays in kana, with が on the か tile and ゃ
-  on the や tile, and a list of 163,461 readings.
+  on the や tile, and a list of 162,243 readings.
 - **Learners and teachers** of English or Japanese spelling.
 
 ## Features
@@ -112,7 +114,7 @@ Or with nothing to install, [play a game in the demo](https://johnmorrisdotca.gi
   its tiles, so every bag can be finished.
 - **English and Japanese.** 144 tiles in each: the English letters, or 45 base
   kana where が plays as か, ゃ as や and を as お. 110,316 English words and
-  163,461 Japanese readings, of 2 to 15 tiles.
+  162,243 Japanese readings, of 2 to 15 tiles.
 - **Wild tiles** that take any letter or kana, and are read as that in every
   word they are part of.
 - **Trades.** A tile you cannot use goes back into the bag for three.
@@ -155,7 +157,7 @@ Each picture is the table the package draws, taken from [the demo](https://johnm
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kumimoji/main/docs/images/kana-desk-dark.webp">
 <img src="https://raw.githubusercontent.com/johnmorrisdotca/kumimoji/main/docs/images/kana-desk-light.webp" alt="A Japanese board of kana tiles on the green table, a crossword of hiragana laid across and down on the grid of empty squares." width="400">
 </picture>
-<br><em><strong>Japanese kana.</strong> 45 base kana tiles, 163,461 readings.</em>
+<br><em><strong>Japanese kana.</strong> 45 base kana tiles, 162,243 readings.</em>
 </td>
 </tr>
 <tr>
@@ -242,7 +244,7 @@ const wrong = decodeGrid("cat/2x")!;
 judgeWithWords(wrong, words).notWords; // → ["tx"]
 
 checkKumimoji(3, "nwosy", "snowy", { level: "hard" }); // → { ok: true }
-checkKumimoji(3, "nwosy", "snows", { level: "hard" }); // → { ok: false, reason: "the grid does not use exactly the tiles of the bag" }
+checkKumimoji(3, "nwosy", "snows", { level: "hard" }); // → { ok: false, reason: "the grid does not use exactly the tiles of the bag", code: "grid-not-the-bag" }
 encodeGrid(tiles); // → "cat/2o/2w"
 ```
 
@@ -390,8 +392,8 @@ fetches when a game is first dealt.
   names only the files that define the tag and register the word lists.
 - **Sizes.** The rules, the computer player and the table of players are
   about 44 kB minified (16 kB gzipped); the table for a page is 34 kB (13 kB).
-  The English list is 606 kB (277 kB gzipped) and the Japanese 718 kB
-  (396 kB), each a file of its own that is fetched only when a game in that
+  The English list is 606 kB (277 kB gzipped) and the Japanese 715 kB
+  (394 kB), each a file of its own that is fetched only when a game in that
   language is first dealt.
 - **Where it runs.** Current Chrome, Edge, Firefox and Safari, on a desk or a
   phone. The rules have no DOM in them and run in Node 22 and later, Deno,
@@ -541,7 +543,7 @@ import { checkKumimoji, generateKumimoji, loadTileWords } from "@johnmorrisdotca
 await loadTileWords("english");
 const dealt = generateKumimoji(3, "hard", 44);
 checkKumimoji(3, dealt.givens, "snowy", { level: "hard" }); // → { ok: true }
-checkKumimoji(3, dealt.givens, "snows", { level: "hard" }); // → { ok: false, reason: "the grid does not use exactly the tiles of the bag" }
+checkKumimoji(3, dealt.givens, "snows", { level: "hard" }); // → { ok: false, reason: "the grid does not use exactly the tiles of the bag", code: "grid-not-the-bag" }
 ```
 
 ### Mount the table with options
@@ -566,6 +568,8 @@ table.destroy();
 
 ### A look of your own
 
+`<kumimoji-table cloth="blue">`, or `cloth: "blue"` when you mount, lays the table in one of the family's five cloths, `green`, `blue`, `red`, `black` or `wood`, the same set as the boards on itsutsu.com; `set({ cloth })` changes it in place, keeping the game, and `theme` is laid over it. `KUMIMOJI_CLOTHS` and `clothVars` hold the colours.
+
 Every colour is a CSS variable on `.km-root`, so a stylesheet or the `theme` option can restyle the table:
 
 ```ts no-run
@@ -670,11 +674,11 @@ import { BASE_KANA, deal, generateKumimoji, loadTileWords, tileKana } from "@joh
 const words = await loadTileWords("japanese");
 [...BASE_KANA].length; // → 45
 [tileKana("が"), tileKana("ゃ"), tileKana("を"), tileKana("っ")]; // → ["か", "や", "お", "つ"]
-words.allowed.size; // → 163461
+words.allowed.size; // → 162243
 words.allowed.has("ことは"); // → true
 
 const dealt = generateKumimoji(7, "medium", 2026, { language: "japanese" });
-deal(dealt.givens, 7).hand.map(words.glyphOf).join(""); // → "よきめたんえら"
+deal(dealt.givens, 7).hand.map(words.glyphOf).join(""); // → "つかてしんきし"
 ```
 
 The tiles are the 45 base hiragana. A word is spelt with the base of each of
@@ -768,7 +772,7 @@ The JSON, as `kumimojiToJSON` writes it:
 {
   "format": 1,
   "game": "kumimoji",
-  "generator": "kumimoji 1.3.1",
+  "generator": "kumimoji 1.5.0",
   "size": 3,
   "level": "hard",
   "seed": 44,
@@ -813,7 +817,7 @@ with its notice too.
 | List | What it is | Where it comes from | Terms |
 | --- | --- | --- | --- |
 | English, `dist/words.en.data.js` | 110,316 words of 2 to 15 letters, English and American spellings | [SCOWL](http://wordlist.aspell.net/) 2020.12.07, sizes 10 to 70 | © 2000–2018 Kevin Atkinson and the authors of the lists SCOWL is built from. Permission to use, copy, modify, distribute and sell for any purpose, **provided the copyright notice appears in all copies, and both it and the permission notice in supporting documentation**. No share-alike. |
-| Japanese, `dist/words.ja.data.js` | 163,461 hiragana readings of 2 to 15 kana, each spelt in the 45 base kana of the tiles | [JMdict](https://www.edrdg.org/jmdict/j_jmdict.html), release 2026-09-28, of the Electronic Dictionary Research and Development Group | **[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)**, with the [EDRDG's conditions](https://www.edrdg.org/edrdg/licence.html). **Attribution is required, and the list, or anything made from it, may be passed on only under the same licence.** |
+| Japanese, `dist/words.ja.data.js` | 162,243 hiragana readings of 2 to 15 kana, each spelt in the 45 base kana of the tiles | [JMdict](https://www.edrdg.org/jmdict/j_jmdict.html), release 2026-11-04, of the Electronic Dictionary Research and Development Group | **[CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)**, with the [EDRDG's conditions](https://www.edrdg.org/edrdg/licence.html). **Attribution is required, and the list, or anything made from it, may be passed on only under the same licence.** |
 
 What that means for a project that uses this package:
 
@@ -886,23 +890,14 @@ as you type. The entries:
 | `deal(bag, handSize)` and `placeFromHand`, `moveOnTable`, `liftToHand`, `draw`, `trade` | The opening hand, and each move, every one returning a new game |
 | `judgeWithWords(tiles, words)` | What is wrong with a grid, or that it is sound |
 | `isFinished(play, verdict)` | Whether the bag is empty, the hand used and every run a word in one piece |
-| `checkKumimoji(size, givens, answer, options?)` | The one check a server runs on a finished grid |
+| `checkKumimoji(size, givens, answer, options?)` | The one check a server runs on a finished grid; a refusal has `reason`, `code`, `values` (`KUMIMOJI_CHECK_REASONS`, `kumimojiRefusal`) |
 | `loadTileWords(language)` | A word list, fetched when first needed |
 | `mountKumimoji(element, options?)` and `<kumimoji-table>` | The table, in one call or one tag |
 | `kumimojiToJSON`, `kumimojiFromJSON` | A game kept, and read back without trusting it |
 
 ### The long tables
 
-The tables of every export for dealing and judging, tiles and grids, playing and keeping a game, a table of players and looking at the table are in [docs/API.md](docs/API.md), and every export of every entry point, with its signature and doc comment, is in the [API reference](https://johnmorrisdotca.github.io/kumimoji/api.html). The types the package exports are listed there too.
-
-The types are `TilePlay`, `Tiles`, `GridVerdict`, `GridRules`, `Run`,
-`RunLine`, `Bounds`, `Square`, `CrossingFit`, `KumimojiDeal`,
-`KumimojiOptions`, `KumimojiCheck`, `KumimojiLevel`, `KumimojiLength`,
-`KumimojiLanguage`, `TileWords`, `TileFaceOf`, `PartyGame`, `PartySettings`,
-`PartyPlayer`, `PartySeat`, `PartyEnding`, `JoinRefusal`, `LeaveRefusal`,
-`ComputerStep`, `ComputerSaid`, `KumimojiSaved`, `KumimojiExported`, `KumimojiStrings`,
-`KumimojiLocale`, `Random`, `Turn`, `Area`, `View`, `MixTile`, `MixShown` and
-`LengthRow`.
+The types, and the tables of every export for dealing and judging, tiles and grids, playing and keeping a game, a table of players and looking at the table are in [docs/API.md](docs/API.md), and every export of every entry point, with its signature and doc comment, is in the [API reference](https://johnmorrisdotca.github.io/kumimoji/api.html). The types the package exports are listed there too.
 
 ### The table
 
@@ -1069,8 +1064,6 @@ kept as text made to be sent, and Itsutsu sends it; the sending is yours); a
 command line; CSV; and any name, art or wording of a published game. Kumimoji
 runs from a static page and costs nothing to host.
 
-Ideas and pull requests are welcome.
-
 ## Architecture
 
 The rules are plain functions over plain data with no DOM: a game is a value,
@@ -1180,16 +1173,16 @@ Kumimoji is one of thirty-two packages, each made for the same site, each at
 
 ```sh
 pnpm install --frozen-lockfile
-pnpm check             # lint, types and tests, including the checks on the README's tables and examples
+pnpm check             # lint, types and tests, the README's own checks among them
 pnpm test:table        # the demo in real browsers, by taps
 pnpm test:package      # pack it as npm does, install it and import every entry
 pnpm test:frameworks   # the six framework examples, built from the packed tarball and played
 pnpm test:readme       # every TypeScript and JavaScript example in this README, type-checked and run
 pnpm site              # build the demo into ./site
-pnpm screenshots:readme  # retake the README's pictures into docs/images (builds the demo first)
+pnpm screenshots:readme  # retake the README's pictures (builds the demo first)
 ```
 
-The pictures are taken on the maintainer's Mac and are retaken only when the look changes; they are in `docs/images` and are not in the package that npm installs.
+The README's pictures are in `docs/images`, which the npm package leaves out.
 
 ## Contributing
 
@@ -1201,7 +1194,7 @@ Please follow the [code of conduct](./CODE_OF_CONDUCT.md). A way to make a check
 
 See [CHANGELOG.md](./CHANGELOG.md).
 
-The latest release, 1.3.1, changes nothing a player sees.
+The latest release, 1.5.0, leaves words that are not for children out of the Japanese list.
 
 ## Licence
 

package/dist/check-reasons.d.ts

@@ -0,0 +1,71 @@
+import type { KumimojiCheck } from "./kumimoji.types.ts";
+/**
+ * Why `checkKumimoji` will not take a grid, as a stable code and the English clause it says: `{name}` is a gap the
+ * check's `values` fill. The clause is what `reason` has always said, word for word; a site that speaks another
+ * language says the code in its own words and puts the values in the gaps.
+ *
+ * | Code | Values |
+ * | --- | --- |
+ * | `no-hand` | `size`: the hand that has no game |
+ * | `not-a-word` | `word`: the first word that is not in the word list |
+ * | `givens-not-bag`, `wild-count-wrong`, `bag-exceeds-set`, `answer-not-grid`, `grid-not-the-bag`, `tiles-apart`, `grid-not-finished` | none |
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_CHECK_REASONS } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(KUMIMOJI_CHECK_REASONS["not-a-word"]);
+ * ```
+ */
+export declare const KUMIMOJI_CHECK_REASONS: {
+    readonly "no-hand": "no Kumimoji with a hand of {size}";
+    readonly "givens-not-bag": "the givens are not a bag of tiles";
+    readonly "wild-count-wrong": "the bag has the wrong number of wild tiles";
+    readonly "bag-exceeds-set": "the bag exceeds the tile set";
+    readonly "answer-not-grid": "the answer is not a grid";
+    readonly "grid-not-the-bag": "the grid does not use exactly the tiles of the bag";
+    readonly "tiles-apart": "the tiles are not all joined";
+    readonly "not-a-word": "{word} is not in the word list";
+    readonly "grid-not-finished": "the grid is not finished";
+};
+/**
+ * A reason `checkKumimoji` can give, by its stable code.
+ *
+ * @example
+ * ```ts
+ * import type { KumimojiCheckCode } from "@johnmorrisdotca/kumimoji";
+ *
+ * const code: KumimojiCheckCode = "tiles-apart";
+ * console.log(code);
+ * ```
+ */
+export type KumimojiCheckCode = keyof typeof KUMIMOJI_CHECK_REASONS;
+/**
+ * The numbers and words that fill a reason's gaps, by the gap's name (see `KUMIMOJI_CHECK_REASONS` for each code's).
+ *
+ * @example
+ * ```ts
+ * import type { KumimojiCheckValues } from "@johnmorrisdotca/kumimoji";
+ *
+ * const values: KumimojiCheckValues = { word: "aow" };
+ * console.log(values);
+ * ```
+ */
+export type KumimojiCheckValues = Readonly<Record<string, string | number>>;
+/**
+ * A refusal: `{ ok: false }`, the English `reason` (the clause of the code with the values in its gaps), the code
+ * and the values.
+ *
+ * @param code - Why the grid is not taken.
+ * @param values - What fills the clause's gaps, where it has any.
+ * @returns The refusal `checkKumimoji` gives.
+ * @example
+ * ```ts
+ * import { kumimojiRefusal } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiRefusal("not-a-word", { word: "aow" }));
+ * ```
+ */
+export declare function kumimojiRefusal(code: KumimojiCheckCode, values?: KumimojiCheckValues): Extract<KumimojiCheck, {
+    ok: false;
+}>;

package/dist/check-reasons.js

@@ -0,0 +1,47 @@
+/**
+ * Why `checkKumimoji` will not take a grid, as a stable code and the English clause it says: `{name}` is a gap the
+ * check's `values` fill. The clause is what `reason` has always said, word for word; a site that speaks another
+ * language says the code in its own words and puts the values in the gaps.
+ *
+ * | Code | Values |
+ * | --- | --- |
+ * | `no-hand` | `size`: the hand that has no game |
+ * | `not-a-word` | `word`: the first word that is not in the word list |
+ * | `givens-not-bag`, `wild-count-wrong`, `bag-exceeds-set`, `answer-not-grid`, `grid-not-the-bag`, `tiles-apart`, `grid-not-finished` | none |
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_CHECK_REASONS } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(KUMIMOJI_CHECK_REASONS["not-a-word"]);
+ * ```
+ */
+export const KUMIMOJI_CHECK_REASONS = {
+    "no-hand": "no Kumimoji with a hand of {size}",
+    "givens-not-bag": "the givens are not a bag of tiles",
+    "wild-count-wrong": "the bag has the wrong number of wild tiles",
+    "bag-exceeds-set": "the bag exceeds the tile set",
+    "answer-not-grid": "the answer is not a grid",
+    "grid-not-the-bag": "the grid does not use exactly the tiles of the bag",
+    "tiles-apart": "the tiles are not all joined",
+    "not-a-word": "{word} is not in the word list",
+    "grid-not-finished": "the grid is not finished",
+};
+/**
+ * A refusal: `{ ok: false }`, the English `reason` (the clause of the code with the values in its gaps), the code
+ * and the values.
+ *
+ * @param code - Why the grid is not taken.
+ * @param values - What fills the clause's gaps, where it has any.
+ * @returns The refusal `checkKumimoji` gives.
+ * @example
+ * ```ts
+ * import { kumimojiRefusal } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiRefusal("not-a-word", { word: "aow" }));
+ * ```
+ */
+export function kumimojiRefusal(code, values) {
+    const reason = KUMIMOJI_CHECK_REASONS[code].replace(/\{(\w+)\}/g, (_gap, name) => String(values?.[name]));
+    return values === undefined ? { ok: false, reason, code } : { ok: false, reason, code, values };
+}

package/dist/check.js

@@ -1,3 +1,4 @@
+import { kumimojiRefusal } from "./check-reasons.js";
 import { decodeGrid, lettersOf, sameLetters } from "./grid.js";
 import { judgeWithWords } from "./judge.js";
 import { KUMIMOJI_SCORE, kumimojiTileCount, kumimojiWildCount, TILE_MIX_TOTAL } from "./tiles.constants.js";
@@ -43,37 +44,37 @@ export function checkKumimoji(size, givens, answer, options = {}) {
         inBag = kumimojiTileCount(size, gameLength, language === "english" ? TILE_MIX_TOTAL : setSize, doubleSet);
     }
     catch {
-        return { ok: false, reason: `no Kumimoji with a hand of ${size}` };
+        return kumimojiRefusal("no-hand", { size });
     }
     const bag = [...givens];
     if (typeof givens !== "string" || bag.length !== inBag)
-        return { ok: false, reason: "the givens are not a bag of tiles" };
+        return kumimojiRefusal("givens-not-bag");
     const expectedWilds = kumimojiWildCount(size, level, inBag);
     if (bag.filter(words.isWild).length !== expectedWilds)
-        return { ok: false, reason: "the bag has the wrong number of wild tiles" };
+        return kumimojiRefusal("wild-count-wrong");
     for (const [tile, count] of lettersOf(bag.filter((each) => !words.isWild(each)))) {
         const face = words.inventoryKey(tile);
         const code = face === null ? null : words.codeOf(face);
         if (code === null || count > (words.mix.get(code) ?? 0) * multiplier)
-            return { ok: false, reason: "the bag exceeds the tile set" };
+            return kumimojiRefusal("bag-exceeds-set");
     }
     const tiles = decodeGrid(answer);
     if (tiles === null)
-        return { ok: false, reason: "the answer is not a grid" };
+        return kumimojiRefusal("answer-not-grid");
     const bagIdentities = bag.map(words.familyKey);
     const tileIdentities = [...tiles.values()].map(words.familyKey);
     if (bagIdentities.some((tile) => tile === null) ||
         tileIdentities.some((tile) => tile === null) ||
         !sameLetters(lettersOf(tileIdentities), lettersOf(bagIdentities))) {
-        return { ok: false, reason: "the grid does not use exactly the tiles of the bag" };
+        return kumimojiRefusal("grid-not-the-bag");
     }
     const verdict = judgeWithWords(tiles, words, { diagonals: options.diagonals === true });
     if (verdict.apart.size > 0)
-        return { ok: false, reason: "the tiles are not all joined" };
+        return kumimojiRefusal("tiles-apart");
     if (verdict.notWords.length > 0)
-        return { ok: false, reason: `${verdict.notWords[0]} is not in the word list` };
+        return kumimojiRefusal("not-a-word", { word: verdict.notWords[0] });
     if (!verdict.sound)
-        return { ok: false, reason: "the grid is not finished" };
+        return kumimojiRefusal("grid-not-finished");
     return { ok: true };
 }
 /** A finished game's leaderboard points (`KUMIMOJI_SCORE`): ten a tile, and up to as much again for speed.

package/dist/element.d.ts

@@ -97,6 +97,9 @@ export declare class KumimojiTable extends ElementBase {
     /** The `controls` attribute, reflected. */
     get controls(): string | null;
     set controls(value: string | number | boolean | null | undefined);
+    /** The `cloth` attribute, reflected: green, blue, red, black or wood. */
+    get cloth(): string | null;
+    set cloth(value: string | number | boolean | null | undefined);
     /** The `theme` attribute, reflected. */
     get theme(): string | null;
     set theme(value: string | number | boolean | null | undefined);

package/dist/element.js

@@ -1,6 +1,7 @@
 import { kumimojiDailySeed } from "./daily.js";
 import { embedDay } from "./embed-day.js";
 import { KUMIMOJI_HANDS } from "./tiles.constants.js";
+import { isCloth } from "./ui/cloth.js";
 import { mountKumimoji } from "./ui/mount.js";
 import { KUMIMOJI_STYLE } from "./ui/style.js";
 const ElementBase = typeof HTMLElement === "undefined" ? class {
@@ -53,6 +54,7 @@ export const KUMIMOJI_EMBED_OPTION_KEYS = Object.keys({
     locale: true,
     strings: true,
     theme: true,
+    cloth: true,
     keep: true,
     controls: true,
     saved: true,
@@ -82,6 +84,7 @@ export class KumimojiTable extends ElementBase {
         "size",
         "width",
         "label",
+        "cloth",
     ];
     #table = null;
     #key = "";
@@ -205,6 +208,13 @@ export class KumimojiTable extends ElementBase {
     set controls(value) {
         this.#write("controls", value);
     }
+    /** The `cloth` attribute, reflected: green, blue, red, black or wood. */
+    get cloth() {
+        return this.getAttribute("cloth");
+    }
+    set cloth(value) {
+        this.#write("cloth", value);
+    }
     /** The `theme` attribute, reflected. */
     get theme() {
         return this.getAttribute("theme");
@@ -319,11 +329,19 @@ export class KumimojiTable extends ElementBase {
                 ? lang
                 : (this.#options.locale ??
                     (this.ownerDocument.documentElement.lang.toLowerCase().startsWith("ja") ? "ja" : "en"));
+            const cloth = isCloth(this.getAttribute("cloth")) ? this.getAttribute("cloth") : this.#options.cloth;
             const keep = isOn(this.getAttribute("keep"), this.#options.keep ?? true);
             const controls = isOn(this.getAttribute("controls"), this.#options.controls ?? true);
             const key = JSON.stringify([language, hand, level, gameLength, diagonals, seed, day, this.#options.saved]);
             if (key === this.#key && this.#table !== null) {
-                this.#table.set({ locale, strings: this.#options.strings, theme: this.#options.theme ?? {}, keep, controls });
+                this.#table.set({
+                    locale,
+                    strings: this.#options.strings,
+                    cloth,
+                    theme: this.#options.theme ?? {},
+                    keep,
+                    controls,
+                });
                 return;
             }
             if (hand !== undefined && !HANDS.includes(hand))
@@ -342,6 +360,7 @@ export class KumimojiTable extends ElementBase {
                 diagonals,
                 seed,
                 locale,
+                cloth,
                 keep,
                 controls,
                 onChange: (saved) => {

package/dist/index.d.ts

@@ -17,6 +17,7 @@
  * disk.
  */
 export * from "./check.ts";
+export * from "./check-reasons.ts";
 export * from "./computer.types.ts";
 export * from "./computerPlay.ts";
 export * from "./computerTurn.ts";

package/dist/index.js

@@ -17,6 +17,7 @@
  * disk.
  */
 export * from "./check.js";
+export * from "./check-reasons.js";
 export * from "./computer.types.js";
 export * from "./computerPlay.js";
 export * from "./computerTurn.js";

package/dist/kumimoji.types.d.ts

@@ -1,3 +1,4 @@
+import type { KumimojiCheckCode, KumimojiCheckValues } from "./check-reasons.ts";
 /** How much of the set a game's bag holds: a short game, half the set, or all of it.
  *
  * @example
@@ -68,13 +69,13 @@ export type KumimojiOptions = {
      */
     diagonals?: boolean;
 };
-/** The answer to "does this grid finish the game?": yes, or no and why.
+/** The answer to "does this grid finish the game?": yes, or no and why, in English (`reason`) and as a stable `code` with `values` a site can say in its own language (`KUMIMOJI_CHECK_REASONS`).
  *
  * @example
  * ```ts
  * import type { KumimojiCheck } from "@johnmorrisdotca/kumimoji";
  *
- * const value: KumimojiCheck = {ok:false,reason:"Not a finished grid"};
+ * const value: KumimojiCheck = {ok:false,reason:"the grid is not finished",code:"grid-not-finished"};
  * console.log(value);
  * ```
  */
@@ -83,6 +84,8 @@ export type KumimojiCheck = {
 } | {
     ok: false;
     reason: string;
+    code: KumimojiCheckCode;
+    values?: KumimojiCheckValues;
 };
 /**
  * A GAME DEALT (`generateKumimoji`): the bag, in the order its tiles come out,

package/dist/ui/cloth.d.ts

@@ -0,0 +1,72 @@
+/**
+ * THE CLOTHS A TABLE MAY BE LAID IN: the same five the whole family offers, and itsutsu.com's boards:
+ * green, blue, red, black and wood. Each is the felt's colour, its deep edge and the ink written on it.
+ * Given to a table as its `--km-felt` and `--km-accent` variables; `theme` is laid over it.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_CLOTHS } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(Object.keys(KUMIMOJI_CLOTHS));
+ * ```
+ */
+export declare const KUMIMOJI_CLOTHS: {
+    readonly green: {
+        readonly felt: "#2f5d4a";
+        readonly deep: "#1f4135";
+        readonly ink: "#f3efe4";
+    };
+    readonly blue: {
+        readonly felt: "#2865a6";
+        readonly deep: "#1a4677";
+        readonly ink: "#f3efe4";
+    };
+    readonly red: {
+        readonly felt: "#a3342e";
+        readonly deep: "#7a231f";
+        readonly ink: "#f3efe4";
+    };
+    readonly black: {
+        readonly felt: "#2f3236";
+        readonly deep: "#1b1d20";
+        readonly ink: "#ece8dc";
+    };
+    readonly wood: {
+        readonly felt: "#e2ba7a";
+        readonly deep: "#c4954f";
+        readonly ink: "#2b1d0e";
+    };
+};
+/** A cloth's name.
+ *
+ * @example
+ * ```ts
+ * import type { Cloth } from "@johnmorrisdotca/kumimoji/ui";
+ * const value: Cloth = "green";
+ * console.log(value);
+ * ```
+ */
+export type Cloth = keyof typeof KUMIMOJI_CLOTHS;
+/** Whether a text names a cloth.
+ *
+ * @param text - Text to parse, validate or format.
+ * @returns Whether a text names a cloth.
+ *
+ * @example
+ * ```ts
+ * import { isCloth } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(isCloth("green"), isCloth("unknown"));
+ * ```
+ */
+export declare function isCloth(text: unknown): text is Cloth;
+/** A cloth as CSS variables; nothing for a name that is not a cloth, so the defaults stay.
+ *
+ * @param cloth - A built-in cloth name; an unknown name leaves the defaults.
+ * @returns The CSS variables to set on the element, or an empty object.
+ *
+ * @example
+ * ```ts
+ * import { clothVars } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(clothVars("green"));
+ * ```
+ */
+export declare function clothVars(cloth: string | undefined | null): Record<`--km-${string}`, string>;

package/dist/ui/cloth.js

@@ -0,0 +1,49 @@
+/**
+ * THE CLOTHS A TABLE MAY BE LAID IN: the same five the whole family offers, and itsutsu.com's boards:
+ * green, blue, red, black and wood. Each is the felt's colour, its deep edge and the ink written on it.
+ * Given to a table as its `--km-felt` and `--km-accent` variables; `theme` is laid over it.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_CLOTHS } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(Object.keys(KUMIMOJI_CLOTHS));
+ * ```
+ */
+export const KUMIMOJI_CLOTHS = {
+    green: { felt: "#2f5d4a", deep: "#1f4135", ink: "#f3efe4" },
+    blue: { felt: "#2865a6", deep: "#1a4677", ink: "#f3efe4" },
+    red: { felt: "#a3342e", deep: "#7a231f", ink: "#f3efe4" },
+    black: { felt: "#2f3236", deep: "#1b1d20", ink: "#ece8dc" },
+    wood: { felt: "#e2ba7a", deep: "#c4954f", ink: "#2b1d0e" },
+};
+/** Whether a text names a cloth.
+ *
+ * @param text - Text to parse, validate or format.
+ * @returns Whether a text names a cloth.
+ *
+ * @example
+ * ```ts
+ * import { isCloth } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(isCloth("green"), isCloth("unknown"));
+ * ```
+ */
+export function isCloth(text) {
+    return typeof text === "string" && Object.hasOwn(KUMIMOJI_CLOTHS, text);
+}
+/** A cloth as CSS variables; nothing for a name that is not a cloth, so the defaults stay.
+ *
+ * @param cloth - A built-in cloth name; an unknown name leaves the defaults.
+ * @returns The CSS variables to set on the element, or an empty object.
+ *
+ * @example
+ * ```ts
+ * import { clothVars } from "@johnmorrisdotca/kumimoji/ui";
+ * console.log(clothVars("green"));
+ * ```
+ */
+export function clothVars(cloth) {
+    if (!isCloth(cloth))
+        return {};
+    const { felt, ink } = KUMIMOJI_CLOTHS[cloth];
+    return { "--km-felt": felt, "--km-accent": felt, "--km-accent-ink": ink };
+}