@johnmorrisdotca/kumimoji 1.2.2 → 1.3.0

package/dist/tileWords.d.ts

@@ -11,6 +11,16 @@ import type { KumimojiLanguage } from "./kumimoji.types.ts";
  * `loadTileWords` fetches and reads it once; `tileWords` hands back the list
  * already loaded, and refuses rather than answering for a list it does not
  * have — a check that could not read the list must not say a word is fine.
+ *
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import type { TileWords } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const value: TileWords = words;
+ * console.log(value);
+ * ```
  */
 export type TileWords = {
     language: KumimojiLanguage;
@@ -43,13 +53,57 @@ export type TileWords = {
     /** Internal tile code for a visible letter or mora. */
     codeOf: (face: string) => string | null;
 };
-/** Front-coded words of one length read back (see `scripts/tile-words.mjs`): a shared-prefix character, then the rest. */
+/** Front-coded words of one length read back (see `scripts/tile-words.mjs`): a shared-prefix character, then the rest.
+ *
+ * @param packed - The front-coded words of one fixed length.
+ * @param length - The game length or decoded word length, as declared.
+ * @returns Front-coded words of one length read back (see `scripts/tile-words.mjs`): a shared-prefix character, then the rest.
+ * @example
+ * ```ts
+ * import { unpackLength } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(unpackLength("0cat2r",3));
+ * ```
+ */
 export declare function unpackLength(packed: string, length: number): string[];
-/** The English list read from its packed data: every word, the words by length, the set's mix, and the functions that turn tiles into words. */
+/** The English list read from its packed data: every word, the words by length, the set's mix, and the functions that turn tiles into words.
+ *
+ * @param data - The packed language-list data to decode.
+ * @returns The English list read from its packed data: every word, the words by length, the set's mix, and the functions that turn tiles into words.
+ * @example
+ * ```ts
+ * import { unpackTileWords } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(unpackTileWords({3:"0cat2r"}).allowed.has("cat"));
+ * ```
+ */
 export declare function unpackTileWords(data: Readonly<Record<number, string>>): TileWords;
-/** Used by `tileWordsModule.ts` only: how to read a list where there is no browser. */
+/** Used by `tileWordsModule.ts` only: how to read a list where there is no browser.
+ *
+ * @param source - The asynchronous loader that supplies the language word list.
+ * @returns Used by `tileWordsModule.ts` only: how to read a list where there is no browser.
+ * @example
+ * ```ts
+ * import { loadTileWords, readTileWordsWith, tileWordsFrom } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * readTileWordsWith(async language => tileWordsFrom(language,{3:"0cat2r"}));
+ * console.log((await loadTileWords("english")).allowed.has("cat"));
+ * ```
+ */
 export declare function readTileWordsWith(source: (language: KumimojiLanguage) => Promise<TileWords>): void;
-/** A list read from its module, for `tileWordsModule.ts`. */
+/** A list read from its module, for `tileWordsModule.ts`.
+ *
+ * @param language - The English or Japanese tile language.
+ * @param data - The packed language-list data to decode.
+ * @returns A list read from its module, for `tileWordsModule.ts`.
+ * @example
+ * ```ts
+ * import { tileWordsFrom } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(tileWordsFrom("english",{3:"0cat2r"}).allowed.size);
+ * ```
+ */
 export declare function tileWordsFrom(language: KumimojiLanguage, data: unknown): TileWords;
 /**
  * THE LIST, ONCE. In a browser (or its worker) it arrives as its own script,
@@ -64,9 +118,42 @@ export declare function tileWordsFrom(language: KumimojiLanguage, data: unknown)
  * branch, and the import with it, is gone before anything is traced. The
  * server reads the list through `tileWordsModule.ts` instead, which only the
  * server's own checks and the tests import.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns THE LIST, ONCE. In a browser (or its worker) it arrives as its own script, fetched by the dynamic import below the first time a Kumimoji needs it.
+ * @example
+ * ```ts
+ * import { loadTileWords } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log((await loadTileWords("english")).allowed.size);
+ * ```
  */
 export declare function loadTileWords(language?: KumimojiLanguage): Promise<TileWords>;
-/** The list already loaded, for judging and dealing. Throws where `loadTileWords` has not yet fetched it: a check that cannot read the list must not answer. */
+/** The list already loaded, for judging and dealing. Throws where `loadTileWords` has not yet fetched it: a check that cannot read the list must not answer.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns The list already loaded, for judging and dealing. Throws where `loadTileWords` has not yet fetched it: a check that cannot read the list must not answer.
+ * @example
+ * ```ts
+ * import { tileWords } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(tileWords("english").allowed.has("cat"));
+ * ```
+ */
 export declare function tileWords(language?: KumimojiLanguage): TileWords;
-/** Whether the list has been fetched yet, for a page to say "loading" rather than throw. */
+/** Whether the list has been fetched yet, for a page to say "loading" rather than throw.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns Whether the list has been fetched yet, for a page to say "loading" rather than throw.
+ * @example
+ * ```ts
+ * import { tileWordsReady } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(tileWordsReady("english"));
+ * ```
+ */
 export declare function tileWordsReady(language?: KumimojiLanguage): boolean;

package/dist/tileWords.js

@@ -2,7 +2,18 @@ import { tileKana } from "./kana.js";
 import { KANA_TILE_START, KANA_WILD_START, kanaTileCode, tileFace } from "./tileFace.js";
 import { JAPANESE_TILE_MIX, TILE_MIX } from "./tiles.constants.js";
 const loaded = new Map();
-/** Front-coded words of one length read back (see `scripts/tile-words.mjs`): a shared-prefix character, then the rest. */
+/** Front-coded words of one length read back (see `scripts/tile-words.mjs`): a shared-prefix character, then the rest.
+ *
+ * @param packed - The front-coded words of one fixed length.
+ * @param length - The game length or decoded word length, as declared.
+ * @returns Front-coded words of one length read back (see `scripts/tile-words.mjs`): a shared-prefix character, then the rest.
+ * @example
+ * ```ts
+ * import { unpackLength } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(unpackLength("0cat2r",3));
+ * ```
+ */
 export function unpackLength(packed, length) {
     const words = [];
     const text = packed.replace(/\s+/g, "");
@@ -18,7 +29,17 @@ export function unpackLength(packed, length) {
     }
     return words;
 }
-/** The English list read from its packed data: every word, the words by length, the set's mix, and the functions that turn tiles into words. */
+/** The English list read from its packed data: every word, the words by length, the set's mix, and the functions that turn tiles into words.
+ *
+ * @param data - The packed language-list data to decode.
+ * @returns The English list read from its packed data: every word, the words by length, the set's mix, and the functions that turn tiles into words.
+ * @example
+ * ```ts
+ * import { unpackTileWords } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(unpackTileWords({3:"0cat2r"}).allowed.has("cat"));
+ * ```
+ */
 export function unpackTileWords(data) {
     const byLength = new Map();
     const allowed = new Set();
@@ -111,11 +132,34 @@ function unpackJapaneseWords(data) {
  * loader that imports them (`tileWordsModule.ts`). Null until one does.
  */
 let fromModule = null;
-/** Used by `tileWordsModule.ts` only: how to read a list where there is no browser. */
+/** Used by `tileWordsModule.ts` only: how to read a list where there is no browser.
+ *
+ * @param source - The asynchronous loader that supplies the language word list.
+ * @returns Used by `tileWordsModule.ts` only: how to read a list where there is no browser.
+ * @example
+ * ```ts
+ * import { loadTileWords, readTileWordsWith, tileWordsFrom } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * readTileWordsWith(async language => tileWordsFrom(language,{3:"0cat2r"}));
+ * console.log((await loadTileWords("english")).allowed.has("cat"));
+ * ```
+ */
 export function readTileWordsWith(source) {
     fromModule = source;
 }
-/** A list read from its module, for `tileWordsModule.ts`. */
+/** A list read from its module, for `tileWordsModule.ts`.
+ *
+ * @param language - The English or Japanese tile language.
+ * @param data - The packed language-list data to decode.
+ * @returns A list read from its module, for `tileWordsModule.ts`.
+ * @example
+ * ```ts
+ * import { tileWordsFrom } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(tileWordsFrom("english",{3:"0cat2r"}).allowed.size);
+ * ```
+ */
 export function tileWordsFrom(language, data) {
     return language === "english"
         ? unpackTileWords(data)
@@ -134,6 +178,17 @@ export function tileWordsFrom(language, data) {
  * branch, and the import with it, is gone before anything is traced. The
  * server reads the list through `tileWordsModule.ts` instead, which only the
  * server's own checks and the tests import.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns THE LIST, ONCE. In a browser (or its worker) it arrives as its own script, fetched by the dynamic import below the first time a Kumimoji needs it.
+ * @example
+ * ```ts
+ * import { loadTileWords } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log((await loadTileWords("english")).allowed.size);
+ * ```
  */
 export async function loadTileWords(language = "english") {
     const already = loaded.get(language);
@@ -153,14 +208,36 @@ export async function loadTileWords(language = "english") {
     loaded.set(language, words);
     return words;
 }
-/** The list already loaded, for judging and dealing. Throws where `loadTileWords` has not yet fetched it: a check that cannot read the list must not answer. */
+/** The list already loaded, for judging and dealing. Throws where `loadTileWords` has not yet fetched it: a check that cannot read the list must not answer.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns The list already loaded, for judging and dealing. Throws where `loadTileWords` has not yet fetched it: a check that cannot read the list must not answer.
+ * @example
+ * ```ts
+ * import { tileWords } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(tileWords("english").allowed.has("cat"));
+ * ```
+ */
 export function tileWords(language = "english") {
     const words = loaded.get(language);
     if (words === undefined)
         throw new Error(`The ${language} Kumimoji words have not been loaded (loadTileWords).`);
     return words;
 }
-/** Whether the list has been fetched yet, for a page to say "loading" rather than throw. */
+/** Whether the list has been fetched yet, for a page to say "loading" rather than throw.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns Whether the list has been fetched yet, for a page to say "loading" rather than throw.
+ * @example
+ * ```ts
+ * import { tileWordsReady } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(tileWordsReady("english"));
+ * ```
+ */
 export function tileWordsReady(language = "english") {
     return loaded.has(language);
 }

package/dist/tileWordsModule.d.ts

@@ -1,4 +1,14 @@
 import { type TileWords } from "./tileWords.ts";
 import type { KumimojiLanguage } from "./kumimoji.types.ts";
-/** The list, read from its module: `loadTileWords` for a caller with no browser. */
+/** The list, read from its module: `loadTileWords` for a caller with no browser.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns The list, read from its module: `loadTileWords` for a caller with no browser.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * console.log((await loadTileWordsFromModule("english")).allowed.size);
+ * ```
+ */
 export declare function loadTileWordsFromModule(language?: KumimojiLanguage): Promise<TileWords>;

package/dist/tileWordsModule.js

@@ -7,7 +7,17 @@ import { loadTileWords, readTileWordsWith, tileWordsFrom } from "./tileWords.js"
  * lists for the browser's sake (see `loadTileWords`).
  */
 readTileWordsWith(async (language) => tileWordsFrom(language, language === "english" ? (await import("./words.en.data.js")).TILE_WORDS_EN : (await import("./words.ja.data.js")).TILE_WORDS_JA));
-/** The list, read from its module: `loadTileWords` for a caller with no browser. */
+/** The list, read from its module: `loadTileWords` for a caller with no browser.
+ *
+ * @param language - The English or Japanese tile language.
+ * @returns The list, read from its module: `loadTileWords` for a caller with no browser.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * console.log((await loadTileWordsFromModule("english")).allowed.size);
+ * ```
+ */
 export function loadTileWordsFromModule(language = "english") {
     return loadTileWords(language);
 }

package/dist/tiles.constants.d.ts

@@ -14,6 +14,12 @@ import type { KumimojiLength } from "./kumimoji.types.ts";
  *
  * To tune the letters, change the counts here. The total is checked by
  * `tiles.test.ts`, so an edit that loses a tile says so.
+ *
+ * @example
+ * ```ts
+ * import { TILE_MIX } from "@johnmorrisdotca/kumimoji";
+ * console.log(TILE_MIX);
+ * ```
  */
 export declare const TILE_MIX: Readonly<Record<string, number>>;
 /**
@@ -29,9 +35,22 @@ export declare const TILE_MIX: Readonly<Record<string, number>>;
  * Fixed here rather than taken from the monthly dictionary refresh, which
  * prints what it measures beside this table (`scripts/word-lists-ja.mjs`): a
  * kept game's bag is checked against these counts.
+ *
+ * @example
+ * ```ts
+ * import { JAPANESE_TILE_MIX } from "@johnmorrisdotca/kumimoji";
+ * console.log(JAPANESE_TILE_MIX);
+ * ```
  */
 export declare const JAPANESE_TILE_MIX: Readonly<Record<string, number>>;
-/** The whole set, counted from the table. */
+/** The whole set, counted from the table.
+ *
+ * @example
+ * ```ts
+ * import { TILE_MIX_TOTAL } from "@johnmorrisdotca/kumimoji";
+ * console.log(TILE_MIX_TOTAL);
+ * ```
+ */
 export declare const TILE_MIX_TOTAL: number;
 /**
  * THERE IS NO BOARD. John, 2026-09-26: "curious if we just have a large board
@@ -40,6 +59,12 @@ export declare const TILE_MIX_TOTAL: number;
  * grows with them (`tableView.ts`), so a grid is as wide and as tall as its
  * player builds it. This is only the most a finished grid may measure either
  * way before the check refuses it unread: fifty tiles in one line is fifty.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_GRID_MOST } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_GRID_MOST);
+ * ```
  */
 export declare const KUMIMOJI_GRID_MOST = 60;
 /**
@@ -47,6 +72,12 @@ export declare const KUMIMOJI_GRID_MOST = 60;
  * 2026-09-26: "you were given seven or 11 starting tiles". Three is for the
  * browser tests alone — a game that can be finished in a few presses — and is
  * never offered on the set-up screen.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_HANDS } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_HANDS);
+ * ```
  */
 export declare const KUMIMOJI_HANDS: {
     readonly tiny: 3;
@@ -56,21 +87,72 @@ export declare const KUMIMOJI_HANDS: {
 /**
  * SHORT GAME TOTALS, by opening hand. Medium and Full derive from the tile
  * inventory in `kumimojiTileCount`; these stay the existing Short lengths.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_BAG } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_BAG);
+ * ```
  */
 export declare const KUMIMOJI_BAG: Readonly<Record<number, number>>;
-/** Wild tiles per original 40/50-tile game, included within the bag total. */
+/** Wild tiles per original 40/50-tile game, included within the bag total.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_WILDS } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_WILDS);
+ * ```
+ */
 export declare const KUMIMOJI_WILDS: Readonly<Record<number, Readonly<Record<"easy" | "medium" | "hard", number>>>>;
-/** Tile count for a selected length and inventory size. Double supplies two sets. */
+/** Tile count for a selected length and inventory size. Double supplies two sets.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param length - The game length or decoded word length, as declared.
+ * @param setSize - The number of physical tiles in the language set.
+ * @param doubleSet - Whether to use two English tile sets.
+ * @returns Tile count for a selected length and inventory size. Double supplies two sets.
+ * @example
+ * ```ts
+ * import { kumimojiTileCount } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiTileCount(7,"short"));
+ * ```
+ */
 export declare function kumimojiTileCount(hand: number, length: KumimojiLength, setSize?: number, doubleSet?: boolean): number;
-/** Wilds scale with the bag; doubling the tile set doubles the wild count too. */
+/** Wilds scale with the bag; doubling the tile set doubles the wild count too.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param level - The difficulty that determines the wildcard allowance.
+ * @param totalTiles - The total number of physical tiles in this bag.
+ * @returns Wilds scale with the bag; doubling the tile set doubles the wild count too.
+ * @example
+ * ```ts
+ * import { kumimojiWildCount, kumimojiTileCount } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiWildCount(7,"easy",kumimojiTileCount(7,"short")));
+ * ```
+ */
 export declare function kumimojiWildCount(hand: number, level: "easy" | "medium" | "hard", totalTiles: number): number;
-/** How many tiles one Draw takes from the bag, once the hand is used and the grid is sound. */
+/** How many tiles one Draw takes from the bag, once the hand is used and the grid is sound.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_DRAW } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_DRAW);
+ * ```
+ */
 export declare const KUMIMOJI_DRAW = 1;
 /**
  * THE TRADE: one awkward tile back into the bag for three new ones — the
  * classic way out of a hand of Q, X and J. The tile given back goes to the
  * bottom of the bag, so it comes round again before the end; offered only
  * while the bag has three to give.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_TRADE } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_TRADE);
+ * ```
  */
 export declare const KUMIMOJI_TRADE: {
     readonly give: 1;
@@ -82,6 +164,12 @@ export declare const KUMIMOJI_TRADE: {
  * speed, which falls away evenly until a game that took half a minute a tile
  * earns no speed at all. A Classic game of fifty tiles in ten minutes is
  * 500 + 300 = 800. The time is the browser's clock, as every solo time here is.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_SCORE } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_SCORE);
+ * ```
  */
 export declare const KUMIMOJI_SCORE: {
     readonly tile: 10;
@@ -99,6 +187,12 @@ export declare const KUMIMOJI_SCORE: {
  * set, and chooses it when the count reaches it (John, 2026-09-28: "when having
  * 6 or more players, we should recommend the double size 288 version"); in
  * Japanese, which has no Double, the Full game instead.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_PARTY } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_PARTY);
+ * ```
  */
 export declare const KUMIMOJI_PARTY: {
     readonly least: 2;

package/dist/tiles.constants.js

@@ -13,6 +13,12 @@
  *
  * To tune the letters, change the counts here. The total is checked by
  * `tiles.test.ts`, so an edit that loses a tile says so.
+ *
+ * @example
+ * ```ts
+ * import { TILE_MIX } from "@johnmorrisdotca/kumimoji";
+ * console.log(TILE_MIX);
+ * ```
  */
 export const TILE_MIX = {
     a: 13, b: 3, c: 3, d: 6, e: 18, f: 3, g: 4, h: 3, i: 12, j: 2, k: 2, l: 5, m: 3,
@@ -31,6 +37,12 @@ export const TILE_MIX = {
  * Fixed here rather than taken from the monthly dictionary refresh, which
  * prints what it measures beside this table (`scripts/word-lists-ja.mjs`): a
  * kept game's bag is checked against these counts.
+ *
+ * @example
+ * ```ts
+ * import { JAPANESE_TILE_MIX } from "@johnmorrisdotca/kumimoji";
+ * console.log(JAPANESE_TILE_MIX);
+ * ```
  */
 export const JAPANESE_TILE_MIX = {
     あ: 2, い: 11, う: 12, え: 1, お: 2, か: 7, き: 6, く: 6, け: 3, こ: 4,
@@ -39,7 +51,14 @@ export const JAPANESE_TILE_MIX = {
     ま: 2, み: 1, む: 1, め: 1, も: 1, や: 2, ゆ: 4, よ: 6, ら: 1, り: 3,
     る: 3, れ: 1, ろ: 1, わ: 1, ん: 11,
 };
-/** The whole set, counted from the table. */
+/** The whole set, counted from the table.
+ *
+ * @example
+ * ```ts
+ * import { TILE_MIX_TOTAL } from "@johnmorrisdotca/kumimoji";
+ * console.log(TILE_MIX_TOTAL);
+ * ```
+ */
 export const TILE_MIX_TOTAL = Object.values(TILE_MIX).reduce((sum, count) => sum + count, 0);
 /**
  * THERE IS NO BOARD. John, 2026-09-26: "curious if we just have a large board
@@ -48,6 +67,12 @@ export const TILE_MIX_TOTAL = Object.values(TILE_MIX).reduce((sum, count) => sum
  * grows with them (`tableView.ts`), so a grid is as wide and as tall as its
  * player builds it. This is only the most a finished grid may measure either
  * way before the check refuses it unread: fifty tiles in one line is fifty.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_GRID_MOST } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_GRID_MOST);
+ * ```
  */
 export const KUMIMOJI_GRID_MOST = 60;
 /**
@@ -55,24 +80,56 @@ export const KUMIMOJI_GRID_MOST = 60;
  * 2026-09-26: "you were given seven or 11 starting tiles". Three is for the
  * browser tests alone — a game that can be finished in a few presses — and is
  * never offered on the set-up screen.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_HANDS } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_HANDS);
+ * ```
  */
 export const KUMIMOJI_HANDS = { tiny: 3, quick: 7, classic: 11 };
 /**
  * SHORT GAME TOTALS, by opening hand. Medium and Full derive from the tile
  * inventory in `kumimojiTileCount`; these stay the existing Short lengths.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_BAG } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_BAG);
+ * ```
  */
 export const KUMIMOJI_BAG = {
     [KUMIMOJI_HANDS.tiny]: 5,
     [KUMIMOJI_HANDS.quick]: 40,
     [KUMIMOJI_HANDS.classic]: 50,
 };
-/** Wild tiles per original 40/50-tile game, included within the bag total. */
+/** Wild tiles per original 40/50-tile game, included within the bag total.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_WILDS } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_WILDS);
+ * ```
+ */
 export const KUMIMOJI_WILDS = {
     [KUMIMOJI_HANDS.tiny]: { easy: 0, medium: 0, hard: 0 },
     [KUMIMOJI_HANDS.quick]: { easy: 6, medium: 3, hard: 0 },
     [KUMIMOJI_HANDS.classic]: { easy: 8, medium: 4, hard: 0 },
 };
-/** Tile count for a selected length and inventory size. Double supplies two sets. */
+/** Tile count for a selected length and inventory size. Double supplies two sets.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param length - The game length or decoded word length, as declared.
+ * @param setSize - The number of physical tiles in the language set.
+ * @param doubleSet - Whether to use two English tile sets.
+ * @returns Tile count for a selected length and inventory size. Double supplies two sets.
+ * @example
+ * ```ts
+ * import { kumimojiTileCount } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiTileCount(7,"short"));
+ * ```
+ */
 export function kumimojiTileCount(hand, length, setSize = TILE_MIX_TOTAL, doubleSet = false) {
     const short = KUMIMOJI_BAG[hand];
     if (short === undefined)
@@ -89,7 +146,19 @@ export function kumimojiTileCount(hand, length, setSize = TILE_MIX_TOTAL, double
         return Math.floor(available / 2);
     return available;
 }
-/** Wilds scale with the bag; doubling the tile set doubles the wild count too. */
+/** Wilds scale with the bag; doubling the tile set doubles the wild count too.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param level - The difficulty that determines the wildcard allowance.
+ * @param totalTiles - The total number of physical tiles in this bag.
+ * @returns Wilds scale with the bag; doubling the tile set doubles the wild count too.
+ * @example
+ * ```ts
+ * import { kumimojiWildCount, kumimojiTileCount } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiWildCount(7,"easy",kumimojiTileCount(7,"short")));
+ * ```
+ */
 export function kumimojiWildCount(hand, level, totalTiles) {
     const short = KUMIMOJI_BAG[hand];
     const wilds = KUMIMOJI_WILDS[hand];
@@ -99,13 +168,26 @@ export function kumimojiWildCount(hand, level, totalTiles) {
         throw new Error(`Invalid Kumimoji tile count: ${totalTiles}.`);
     return Math.round((wilds[level] * totalTiles) / short);
 }
-/** How many tiles one Draw takes from the bag, once the hand is used and the grid is sound. */
+/** How many tiles one Draw takes from the bag, once the hand is used and the grid is sound.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_DRAW } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_DRAW);
+ * ```
+ */
 export const KUMIMOJI_DRAW = 1;
 /**
  * THE TRADE: one awkward tile back into the bag for three new ones — the
  * classic way out of a hand of Q, X and J. The tile given back goes to the
  * bottom of the bag, so it comes round again before the end; offered only
  * while the bag has three to give.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_TRADE } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_TRADE);
+ * ```
  */
 export const KUMIMOJI_TRADE = { give: 1, take: 3 };
 /**
@@ -114,6 +196,12 @@ export const KUMIMOJI_TRADE = { give: 1, take: 3 };
  * speed, which falls away evenly until a game that took half a minute a tile
  * earns no speed at all. A Classic game of fifty tiles in ten minutes is
  * 500 + 300 = 800. The time is the browser's clock, as every solo time here is.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_SCORE } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_SCORE);
+ * ```
  */
 export const KUMIMOJI_SCORE = { tile: 10, slowestMsATile: 30000 };
 /**
@@ -128,5 +216,11 @@ export const KUMIMOJI_SCORE = { tile: 10, slowestMsATile: 30000 };
  * set, and chooses it when the count reaches it (John, 2026-09-28: "when having
  * 6 or more players, we should recommend the double size 288 version"); in
  * Japanese, which has no Double, the Full game instead.
+ *
+ * @example
+ * ```ts
+ * import { KUMIMOJI_PARTY } from "@johnmorrisdotca/kumimoji";
+ * console.log(KUMIMOJI_PARTY);
+ * ```
  */
 export const KUMIMOJI_PARTY = { least: 2, most: 8, nameMost: 20, doubleFrom: 6 };