@johnmorrisdotca/kumimoji 1.2.2 → 1.3.1

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();
@@ -30,7 +51,7 @@ export function unpackTileWords(data) {
     }
     const letters = [...Object.keys(TILE_MIX)];
     const assigned = new Map(letters.map((letter) => [letter.toUpperCase(), letter]));
-    const soundOf = (tile) => (tile === "*" ? null : assigned.get(tile) ?? (/^[a-z]$/.test(tile) ? tile : null));
+    const soundOf = (tile) => tile === "*" ? null : (assigned.get(tile) ?? (/^[a-z]$/.test(tile) ? tile : null));
     const isWild = (tile) => tile === "*" || assigned.has(tile);
     return {
         language: "english",
@@ -73,8 +94,12 @@ function unpackJapaneseWords(data) {
             allowed.add([...word].map((tile) => tileFace(tile).glyph).join(""));
     }
     const mix = new Map(Object.entries(JAPANESE_TILE_MIX).map(([face, count]) => [kanaTileCode(face), count]));
-    const isTile = (tile) => tile.length === 1 && tile.codePointAt(0) - KANA_TILE_START >= 0 && tile.codePointAt(0) - KANA_TILE_START < kana.length;
-    const isAssignedWild = (tile) => tile.length === 1 && tile.codePointAt(0) - KANA_WILD_START >= 0 && tile.codePointAt(0) - KANA_WILD_START < kana.length;
+    const isTile = (tile) => tile.length === 1 &&
+        tile.codePointAt(0) - KANA_TILE_START >= 0 &&
+        tile.codePointAt(0) - KANA_TILE_START < kana.length;
+    const isAssignedWild = (tile) => tile.length === 1 &&
+        tile.codePointAt(0) - KANA_WILD_START >= 0 &&
+        tile.codePointAt(0) - KANA_WILD_START < kana.length;
     const isWild = (tile) => tile === "*" || isAssignedWild(tile);
     const soundOf = (tile) => (isTile(tile) || isAssignedWild(tile) ? tileFace(tile).glyph : null);
     const identity = (tile) => (isWild(tile) ? "*" : isTile(tile) ? tileFace(tile).glyph : null);
@@ -111,11 +136,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 +182,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);
@@ -141,9 +200,10 @@ export async function loadTileWords(language = "english") {
         return already;
     let words;
     if (typeof window !== "undefined") {
-        words = language === "english"
-            ? unpackTileWords((await import("./words.en.data.js")).TILE_WORDS_EN)
-            : unpackJapaneseWords((await import("./words.ja.data.js")).TILE_WORDS_JA);
+        words =
+            language === "english"
+                ? unpackTileWords((await import("./words.en.data.js")).TILE_WORDS_EN)
+                : unpackJapaneseWords((await import("./words.ja.data.js")).TILE_WORDS_JA);
     }
     else {
         if (fromModule === null)
@@ -153,14 +213,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. */
+import { type TileWords } from "./tileWords.ts";
+/** 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

@@ -6,8 +6,20 @@ import { loadTileWords, readTileWordsWith, tileWordsFrom } from "./tileWords.js"
  * page's components never import it, so no page's server function carries the
  * 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. */
+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.
+ *
+ * @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;