@johnmorrisdotca/kumimoji 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to this project are written down here. The format follows
 
 ## [Unreleased]
 
+## [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 +196,8 @@ 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.4.0...HEAD
+[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/README.md

@@ -10,7 +10,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="679.3 kB minified and gzipped" src="https://img.shields.io/badge/min%2Bgzip-679.3%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>
 
@@ -242,7 +242,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"
 ```
 
@@ -541,7 +541,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 +566,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
@@ -768,7 +770,7 @@ The JSON, as `kumimojiToJSON` writes it:
 {
   "format": 1,
   "game": "kumimoji",
-  "generator": "kumimoji 1.3.1",
+  "generator": "kumimoji 1.4.0",
   "size": 3,
   "level": "hard",
   "seed": 44,
@@ -886,23 +888,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
 
@@ -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.4.0, gives a check's reason as a code beside the English, and lets a table be laid in the family's five cloths.
 
 ## 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 };
+}

package/dist/ui/mount.d.ts

@@ -2,6 +2,7 @@ import { type KumimojiSaved } from "../export.ts";
 import type { KumimojiDeal, KumimojiLanguage, KumimojiLength, KumimojiLevel } from "../kumimoji.types.ts";
 import { type TilePlay } from "../play.ts";
 import { type KumimojiLocale, type KumimojiStrings } from "../strings.ts";
+import { type Cloth } from "./cloth.ts";
 /**
  * Optional initial game, presentation, readiness and callback choices.
  * With nothing, it is a short English game from a hand of seven, with some wild tiles.
@@ -39,6 +40,8 @@ export type KumimojiTableOptions = {
     strings?: Partial<KumimojiStrings>;
     /** CSS variables set on the table itself, which win in light and dark alike: `{ "--km-felt": "#23405a" }`. */
     theme?: Readonly<Record<string, string>>;
+    /** The cloth the table is laid in: "green", "blue", "red", "black" or "wood", the family's five. `theme` is laid over it. */
+    cloth?: Cloth;
     /** Whether the table offers saving and loading. True by default. */
     keep?: boolean;
     /** Show native play-action buttons; a host hiding them supplies its own actions. */
@@ -63,7 +66,7 @@ export type KumimojiTableHandle = {
     /** Settles once the initial deal or restored game is ready. */
     readonly ready: Promise<void>;
     /** Change presentation and controls without redealing. */
-    set: (options: Pick<KumimojiTableOptions, "locale" | "strings" | "theme" | "keep" | "controls">) => void;
+    set: (options: Pick<KumimojiTableOptions, "locale" | "strings" | "cloth" | "theme" | "keep" | "controls">) => void;
     /** The game as it stands, or null while it is being dealt. */
     play: () => TilePlay | null;
     /** The game as it would be saved (`kumimojiToJSON`), or null while it is being dealt. */

package/dist/ui/mount.js

@@ -5,6 +5,7 @@ import { deal, isFinished, liftToHand, moveOnTable, placeFromHand, swapWithHand
 import { kumimojiStrings } from "../strings.js";
 import { KUMIMOJI_HANDS } from "../tiles.constants.js";
 import { loadTileWords } from "../tileWords.js";
+import { clothVars, isCloth } from "./cloth.js";
 import { button, node, tableDrawing } from "./draw.js";
 import { KUMIMOJI_STYLE } from "./style.js";
 /** Hand a string to the person as a file of that name. */
@@ -80,8 +81,17 @@ export function mountKumimoji(target, options = {}) {
     const root = node("div", "km-root");
     root.dataset.testid = "km-root";
     root.dataset.state = "dealing";
-    for (const [name, value] of Object.entries(current.theme ?? {}))
-        root.style.setProperty(name, value);
+    const wear = (cloth, theme) => {
+        for (const name of Object.keys(clothVars("green")))
+            root.style.removeProperty(name);
+        for (const [name, value] of Object.entries({ ...clothVars(cloth), ...theme }))
+            root.style.setProperty(name, value);
+        if (isCloth(cloth))
+            root.dataset.cloth = cloth;
+        else
+            delete root.dataset.cloth;
+    };
+    wear(current.cloth, current.theme ?? {});
     const style = node("style");
     style.textContent = KUMIMOJI_STYLE;
     const status = node("p", "km-status");
@@ -311,9 +321,8 @@ export function mountKumimoji(target, options = {}) {
             for (const name of Object.keys(current.theme ?? {}))
                 if (changes.theme !== undefined && !(name in changes.theme))
                     root.style.removeProperty(name);
-            if (changes.theme !== undefined)
-                for (const [name, value] of Object.entries(changes.theme))
-                    root.style.setProperty(name, value);
+            if (changes.theme !== undefined || "cloth" in changes)
+                wear("cloth" in changes ? changes.cloth : current.cloth, changes.theme ?? current.theme ?? {});
             current = { ...current, ...changes };
             if (changes.locale !== undefined)
                 session.locale = changes.locale;

package/dist/ui/style.d.ts

@@ -9,4 +9,4 @@
  * console.log(KUMIMOJI_STYLE.includes(".km-root")); // true
  * ```
  */
-export declare const KUMIMOJI_STYLE = "\n.km-root {\n  --km-square: 44px; --km-felt: #2f5d4a; --km-grid-line: rgba(255,255,255,.12); --km-tile: #f3e6c8; --km-tile-ink: #2a2118;\n  --km-wild: #f6d27a; --km-wrong: #d9534f; --km-held: #ffcf3f; --km-ink: #1f2320; --km-panel: #f7f3ea;\n  --km-line: rgba(20,20,20,.35); --km-accent: #2f5d4a; --km-accent-ink: #fff;\n  --km-radius: 12px; --km-font: system-ui, -apple-system, \"Segoe UI\", sans-serif;\n  display: grid; gap: 10px; min-width: 0; color: var(--km-ink); font-family: var(--km-font); font-size: 15px;\n}\n@media (prefers-color-scheme: dark) {\n  .km-root { --km-felt: #1e3a2f; --km-ink: #ece8dc; --km-panel: #1d201e; --km-line: rgba(255,255,255,.25); --km-accent: #6fb08f; --km-accent-ink: #10150f; }\n}\n.km-root > * { min-width: 0; }\n.km-status { margin: 0; min-height: 1.4em; font-variant-numeric: tabular-nums; }\n.km-board { background: var(--km-felt); border-radius: var(--km-radius); padding: 10px; overflow: auto; max-height: 70vh; }\n.km-grid { display: grid; gap: 2px; width: max-content; margin: 0 auto; }\n.km-square { width: var(--km-square); height: var(--km-square); border: 0; border-radius: 5px; background: var(--km-grid-line); padding: 0; cursor: pointer; touch-action: manipulation; }\n.km-tile { display: grid; place-items: center; width: var(--km-square); height: var(--km-square); border-radius: 6px; border: 0; padding: 0;\n  background: var(--km-tile); color: var(--km-tile-ink); font: 700 calc(var(--km-square) * .55)/1 var(--km-font); text-transform: uppercase;\n  box-shadow: 0 2px 0 rgba(0,0,0,.35); cursor: pointer; touch-action: manipulation; }\n.km-japanese .km-tile { font-size: calc(var(--km-square) * .52); text-transform: none; }\n.km-wild { background: var(--km-wild); }\n.km-misspelt { box-shadow: 0 0 0 3px var(--km-wrong) inset, 0 2px 0 rgba(0,0,0,.35); }\n.km-apart { opacity: .6; }\n.km-held { outline: 3px solid var(--km-held); outline-offset: 1px; }\n.km-square:focus-visible, .km-in-hand:focus-visible, .km-button:focus-visible, .km-keep-title:focus-visible { outline: 3px solid var(--km-held); outline-offset: 2px; }\n.km-notes { margin: 0; min-height: 1.4em; font-size: 14px; opacity: .8; overflow-wrap: anywhere; }\n.km-hand { display: flex; flex-wrap: wrap; gap: 6px; min-height: calc(var(--km-square) + 16px); align-items: center; padding: 8px; border-radius: 10px; background: var(--km-panel); }\n.km-empty { opacity: .6; font-size: 14px; }\n.km-picker { display: flex; flex-wrap: wrap; gap: 4px; align-items: center; }\n.km-picker:empty { display: none; }\n.km-picker-title { width: 100%; font-size: 14px; }\n.km-picker .km-button { padding: 0 8px; text-transform: uppercase; }\n.km-japanese .km-picker .km-button { text-transform: none; }\n.km-controls[hidden] { display: none; }\n.km-controls { display: flex; flex-wrap: wrap; gap: 8px; }\n.km-button { font: inherit; min-height: 44px; min-width: 44px; padding: 0 14px; border-radius: 8px; border: 1px solid var(--km-line); background: var(--km-panel); color: var(--km-ink); cursor: pointer; touch-action: manipulation; }\n.km-button:disabled { opacity: .45; cursor: default; }\n.km-primary { background: var(--km-accent); color: var(--km-accent-ink); border-color: transparent; }\n.km-keep { border-radius: 10px; background: var(--km-panel); padding: 0 10px; }\n.km-keep[open] { padding-bottom: 10px; }\n.km-keep-title { min-height: 44px; display: flex; align-items: center; font-weight: 600; cursor: pointer; }\n.km-note { margin: 8px 0 0; min-height: 1.4em; font-size: 13px; }\n";
+export declare const KUMIMOJI_STYLE = "\n.km-root {\n  --km-square: 44px; --km-felt: #2f5d4a; --km-grid-line: rgba(255,255,255,.12); --km-tile: #f3e6c8; --km-tile-ink: #2a2118;\n  --km-wild: #f6d27a; --km-wrong: #d9534f; --km-held: #ffcf3f; --km-ink: #1f2320; --km-panel: #f7f3ea;\n  --km-line: rgba(20,20,20,.35); --km-accent: #2f5d4a; --km-accent-ink: #fff;\n  --km-radius: 12px; --km-font: system-ui, -apple-system, \"Segoe UI\", sans-serif;\n  display: grid; gap: 10px; min-width: 0; color: var(--km-ink); font-family: var(--km-font); font-size: 15px;\n}\n@media (prefers-color-scheme: dark) {\n  .km-root { --km-felt: #1e3a2f; --km-ink: #ece8dc; --km-panel: #1d201e; --km-line: rgba(255,255,255,.25); --km-accent: #6fb08f; --km-accent-ink: #10150f; }\n}\n.km-root > * { min-width: 0; }\n.km-status { margin: 0; min-height: 1.4em; font-variant-numeric: tabular-nums; }\n.km-root, .km-root * { line-height: 1.35; }\n.km-board { background: var(--km-felt); border-radius: var(--km-radius); padding: 10px; overflow: auto; max-height: 70vh; }\n.km-grid { display: grid; gap: 2px; width: max-content; margin: 0 auto; }\n.km-square { width: var(--km-square); height: var(--km-square); border: 0; border-radius: 5px; background: var(--km-grid-line); padding: 0; cursor: pointer; touch-action: manipulation; }\n.km-tile { display: grid; place-items: center; width: var(--km-square); height: var(--km-square); border-radius: 6px; border: 0; padding: 0;\n  background: var(--km-tile); color: var(--km-tile-ink); font: 700 calc(var(--km-square) * .55)/1 var(--km-font); text-transform: uppercase;\n  box-shadow: 0 2px 0 rgba(0,0,0,.35); cursor: pointer; touch-action: manipulation; }\n.km-japanese .km-tile { font-size: calc(var(--km-square) * .52); text-transform: none; }\n.km-wild { background: var(--km-wild); }\n.km-misspelt { box-shadow: 0 0 0 3px var(--km-wrong) inset, 0 2px 0 rgba(0,0,0,.35); }\n.km-apart { opacity: .6; }\n.km-held { outline: 3px solid var(--km-held); outline-offset: 1px; }\n.km-square:focus-visible, .km-in-hand:focus-visible, .km-button:focus-visible, .km-keep-title:focus-visible { outline: 3px solid var(--km-held); outline-offset: 2px; }\n.km-notes { margin: 0; min-height: 1.4em; font-size: 14px; opacity: .8; overflow-wrap: anywhere; }\n.km-hand { display: flex; flex-wrap: wrap; gap: 6px; min-height: calc(var(--km-square) + 16px); align-items: center; padding: 8px; border-radius: 10px; background: var(--km-panel); }\n.km-empty { opacity: .6; font-size: 14px; }\n.km-picker { display: flex; flex-wrap: wrap; gap: 4px; align-items: center; }\n.km-picker:empty { display: none; }\n.km-picker-title { width: 100%; font-size: 14px; }\n.km-picker .km-button { padding: 0 8px; text-transform: uppercase; }\n.km-japanese .km-picker .km-button { text-transform: none; }\n.km-controls[hidden] { display: none; }\n.km-controls { display: flex; flex-wrap: wrap; gap: 8px; }\n.km-button { font: inherit; min-height: 44px; min-width: 44px; padding: 0 14px; border-radius: 8px; border: 1px solid var(--km-line); background: var(--km-panel); color: var(--km-ink); cursor: pointer; touch-action: manipulation; }\n.km-button:disabled { opacity: .45; cursor: default; }\n.km-primary { background: var(--km-accent); color: var(--km-accent-ink); border-color: transparent; }\n.km-keep { border-radius: 10px; background: var(--km-panel); padding: 0 10px; }\n.km-keep[open] { padding-bottom: 10px; }\n.km-keep-title { min-height: 44px; display: flex; align-items: center; font-weight: 600; cursor: pointer; }\n.km-note { margin: 8px 0 0; min-height: 1.4em; font-size: 13px; }\n";

package/dist/ui/style.js

@@ -22,6 +22,7 @@ export const KUMIMOJI_STYLE = `
 }
 .km-root > * { min-width: 0; }
 .km-status { margin: 0; min-height: 1.4em; font-variant-numeric: tabular-nums; }
+.km-root, .km-root * { line-height: 1.35; }
 .km-board { background: var(--km-felt); border-radius: var(--km-radius); padding: 10px; overflow: auto; max-height: 70vh; }
 .km-grid { display: grid; gap: 2px; width: max-content; margin: 0 auto; }
 .km-square { width: var(--km-square); height: var(--km-square); border: 0; border-radius: 5px; background: var(--km-grid-line); padding: 0; cursor: pointer; touch-action: manipulation; }

package/dist/ui.d.ts

@@ -5,5 +5,6 @@
  */
 export { KUMIMOJI_STRINGS, type KumimojiLocale, type KumimojiStrings, kumimojiSay, kumimojiStrings, } from "./strings.ts";
 export { BOARD_LEAST, BOARD_MARGIN, type BoardModel, type BoardSquare, boardModel, type TileMark } from "./ui/board.ts";
+export { type Cloth, clothVars, isCloth, KUMIMOJI_CLOTHS } from "./ui/cloth.ts";
 export { type KumimojiTableHandle, type KumimojiTableOptions, mountKumimoji } from "./ui/mount.ts";
 export { KUMIMOJI_STYLE } from "./ui/style.ts";

package/dist/ui.js

@@ -5,5 +5,6 @@
  */
 export { KUMIMOJI_STRINGS, kumimojiSay, kumimojiStrings, } from "./strings.js";
 export { BOARD_LEAST, BOARD_MARGIN, boardModel } from "./ui/board.js";
+export { clothVars, isCloth, KUMIMOJI_CLOTHS } from "./ui/cloth.js";
 export { mountKumimoji } from "./ui/mount.js";
 export { KUMIMOJI_STYLE } from "./ui/style.js";

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * console.log(KUMIMOJI_VERSION);
  * ```
  */
-export declare const KUMIMOJI_VERSION = "1.3.1";
+export declare const KUMIMOJI_VERSION = "1.4.0";

package/dist/version.js

@@ -6,4 +6,4 @@
  * console.log(KUMIMOJI_VERSION);
  * ```
  */
-export const KUMIMOJI_VERSION = "1.3.1";
+export const KUMIMOJI_VERSION = "1.4.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/kumimoji",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Kumimoji 組み文字 — Crossword tile game in English and Japanese: seeded bags, solo races, two-to-eight-player tables, word lists and a playable table for React, Vue, Svelte, Angular or plain HTML. Zero dependencies.",
   "keywords": [
     "ai",