@johnmorrisdotca/kumimoji 1.2.2 → 1.3.0

package/dist/grid.js

@@ -1,14 +1,46 @@
 import { KUMIMOJI_GRID_MOST } from "./tiles.constants.js";
-/** A square's name, "row,col". */
+/** A square's name, "row,col".
+ *
+ * @param row - The integer row coordinate, which may be negative.
+ * @param col - The integer column coordinate, which may be negative.
+ * @returns A square's name, "row,col".
+ * @example
+ * ```ts
+ * import { squareAt } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(squareAt(-1,2));
+ * ```
+ */
 export function squareAt(row, col) {
     return `${row},${col}`;
 }
-/** A square's row and column, from its name. */
+/** A square's row and column, from its name.
+ *
+ * @param square - The row,column square name.
+ * @returns A square's row and column, from its name.
+ * @example
+ * ```ts
+ * import { placeOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(placeOf("-1,2"));
+ * ```
+ */
 export function placeOf(square) {
     const [row, col] = square.split(",").map(Number);
     return { row: row, col: col };
 }
-/** The rows and columns the tiles stand within, or null for no tiles. */
+/** The rows and columns the tiles stand within, or null for no tiles.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @returns The rows and columns the tiles stand within, or null for no tiles.
+ * @example
+ * ```ts
+ * import { boundsOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(boundsOf(tiles));
+ * ```
+ */
 export function boundsOf(tiles) {
     let bounds = null;
     for (const square of tiles.keys()) {
@@ -20,7 +52,18 @@ export function boundsOf(tiles) {
     }
     return bounds;
 }
-/** A grid as a string, drawn from its own top-left tile: `cat/2o/2w`. `decodeGrid` reads it back. */
+/** A grid as a string, drawn from its own top-left tile: `cat/2o/2w`. `decodeGrid` reads it back.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @returns A grid as a string, drawn from its own top-left tile: `cat/2o/2w`. `decodeGrid` reads it back.
+ * @example
+ * ```ts
+ * import { encodeGrid } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(encodeGrid(tiles));
+ * ```
+ */
 export function encodeGrid(tiles) {
     const bounds = boundsOf(tiles);
     if (bounds === null)
@@ -48,6 +91,15 @@ export function encodeGrid(tiles) {
  * A grid read back, its first row at row 0, or null for anything that is not
  * one: a stray character, a capital, a grid wider or taller than any grid of
  * fifty tiles can be. An empty string is no tiles.
+ *
+ * @param code - The encoded grid or progress text.
+ * @returns A grid read back, its first row at row 0, or null for anything that is not one: a stray character, a capital, a grid wider or taller than any grid of fifty tiles can be. An empty string is no tiles.
+ * @example
+ * ```ts
+ * import { decodeGrid } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(decodeGrid("cat"));
+ * ```
  */
 export function decodeGrid(code) {
     if (typeof code !== "string")
@@ -97,7 +149,17 @@ export function decodeGrid(code) {
     }
     return tiles;
 }
-/** How many of each letter. */
+/** How many of each letter.
+ *
+ * @param letters - The iterable tile letters to count.
+ * @returns How many of each letter.
+ * @example
+ * ```ts
+ * import { lettersOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(lettersOf("cat"));
+ * ```
+ */
 export function lettersOf(letters) {
     const counts = new Map();
     for (const letter of letters)
@@ -105,7 +167,18 @@ export function lettersOf(letters) {
             counts.set(letter, (counts.get(letter) ?? 0) + 1);
     return counts;
 }
-/** Whether two tallies hold the same letters, as many of each. */
+/** Whether two tallies hold the same letters, as many of each.
+ *
+ * @param a - The first letter-count map.
+ * @param b - The second letter-count map.
+ * @returns Whether two tallies hold the same letters, as many of each.
+ * @example
+ * ```ts
+ * import { lettersOf, sameLetters } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(sameLetters(lettersOf("cat"),lettersOf("act")));
+ * ```
+ */
 export function sameLetters(a, b) {
     if (a.size !== b.size)
         return false;
@@ -121,6 +194,12 @@ const STEP = { across: [0, 1], down: [1, 0], downRight: [1, 1], downLeft: [1, -1
  * at a corner are what every crossword is full of — the letter above a word
  * and the one beside it — so a pair is free, and only three or more in a
  * line are a diagonal word.
+ *
+ * @example
+ * ```ts
+ * import { DIAGONAL_RUN_LEAST } from "@johnmorrisdotca/kumimoji";
+ * console.log(DIAGONAL_RUN_LEAST);
+ * ```
  */
 export const DIAGONAL_RUN_LEAST = 3;
 function runsAlong(tiles, line, least) {
@@ -147,6 +226,17 @@ function runsAlong(tiles, line, least) {
  * Every run the grid is read by: two or more tiles across, then down, and
  * with Diagonals three or more down to the right, then down to the left. A
  * tile with nothing beside it in a line is no run.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns Every run the grid is read by: two or more tiles across, then down, and with Diagonals three or more down to the right, then down to the left. A tile with nothing beside it in a line is no run.
+ * @example
+ * ```ts
+ * import { runsOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(runsOf(tiles));
+ * ```
  */
 export function runsOf(tiles, rules = {}) {
     const runs = [...runsAlong(tiles, "across", 2), ...runsAlong(tiles, "down", 2)];
@@ -160,6 +250,17 @@ export function runsOf(tiles, rules = {}) {
  * other in one of those runs are joined too: a diagonal word holds a
  * crossword together as a word across does. A pair touching at a corner is
  * never a link, because it is never read.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param links - The runs connecting groups; computed from the grid when omitted.
+ * @returns The tiles in groups that touch across or down, largest first. With `links` — the diagonal runs a grid with Diagonals reads — the tiles next to each other in one of those runs are joined too: a diagonal word holds a crossword together as a word across does. A pair touching at a corner is never a link, because it is never read.
+ * @example
+ * ```ts
+ * import { groupsOf } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(groupsOf(tiles));
+ * ```
  */
 export function groupsOf(tiles, links = []) {
     const joined = new Map();
@@ -193,7 +294,21 @@ export function groupsOf(tiles, links = []) {
     }
     return groups.sort((a, b) => b.length - a.length);
 }
-/** A grid judged against any test of a word: `isWord` answers for a run as spelt, and `readable` says how to name one that is not. `judgeWithWords` is this with a language's list. */
+/** A grid judged against any test of a word: `isWord` answers for a run as spelt, and `readable` says how to name one that is not. `judgeWithWords` is this with a language's list.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param isWord - The predicate that accepts a readable word.
+ * @param readable - The conversion from tile codes to readable words.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns A grid judged against any test of a word: `isWord` answers for a run as spelt, and `readable` says how to name one that is not. `judgeWithWords` is this with a language's list.
+ * @example
+ * ```ts
+ * import { judgeGrid } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(judgeGrid(tiles,word=>word==="cat"));
+ * ```
+ */
 export function judgeGrid(tiles, isWord, readable = (word) => word, rules = {}) {
     const misspelt = new Set();
     const notWords = [];

package/dist/help.d.ts

@@ -12,9 +12,42 @@ import type { TileWords } from "./tileWords.ts";
  * Only the hand's own tiles are read — a wild is left for the player to place
  * — and nothing on the table is moved.
  */
-/** How many words one hand offers before the presses go round again: the longest first. */
+/** How many words one hand offers before the presses go round again: the longest first.
+ *
+ * @example
+ * ```ts
+ * import { HELP_WORDS_MOST } from "@johnmorrisdotca/kumimoji";
+ * console.log(HELP_WORDS_MOST);
+ * ```
+ */
 export declare const HELP_WORDS_MOST = 40;
-/** The words the hand's own tiles spell, longest first and then in the list's order; wilds are not used. */
+/** The words the hand's own tiles spell, longest first and then in the list's order; wilds are not used.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns The words the hand's own tiles spell, longest first and then in the list's order; wilds are not used.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { wordsInHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * console.log(wordsInHand(["c","a","t"],words));
+ * ```
+ */
 export declare function wordsInHand(hand: readonly string[], words: TileWords): string[];
-/** The hand with `word`'s tiles first, in its order, and the rest after them as they were. */
+/** The hand with `word`'s tiles first, in its order, and the rest after them as they were.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param word - The encoded word to lay or spell.
+ * @returns The hand with `word`'s tiles first, in its order, and the rest after them as they were.
+ * @example
+ * ```ts
+ * import { deal, handSpelling } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * const play = deal("catdog",3);
+ * console.log(handSpelling(play,"cat").tiles);
+ * ```
+ */
 export declare function handSpelling(play: TilePlay, word: string): TilePlay;

package/dist/help.js

@@ -10,9 +10,29 @@
  * Only the hand's own tiles are read — a wild is left for the player to place
  * — and nothing on the table is moved.
  */
-/** How many words one hand offers before the presses go round again: the longest first. */
+/** How many words one hand offers before the presses go round again: the longest first.
+ *
+ * @example
+ * ```ts
+ * import { HELP_WORDS_MOST } from "@johnmorrisdotca/kumimoji";
+ * console.log(HELP_WORDS_MOST);
+ * ```
+ */
 export const HELP_WORDS_MOST = 40;
-/** The words the hand's own tiles spell, longest first and then in the list's order; wilds are not used. */
+/** The words the hand's own tiles spell, longest first and then in the list's order; wilds are not used.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns The words the hand's own tiles spell, longest first and then in the list's order; wilds are not used.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { wordsInHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * console.log(wordsInHand(["c","a","t"],words));
+ * ```
+ */
 export function wordsInHand(hand, words) {
     const have = new Map();
     for (const tile of hand)
@@ -42,7 +62,20 @@ export function wordsInHand(hand, words) {
     }
     return found;
 }
-/** The hand with `word`'s tiles first, in its order, and the rest after them as they were. */
+/** The hand with `word`'s tiles first, in its order, and the rest after them as they were.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param word - The encoded word to lay or spell.
+ * @returns The hand with `word`'s tiles first, in its order, and the rest after them as they were.
+ * @example
+ * ```ts
+ * import { deal, handSpelling } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * const play = deal("catdog",3);
+ * console.log(handSpelling(play,"cat").tiles);
+ * ```
+ */
 export function handSpelling(play, word) {
     const rest = [...play.hand];
     const front = [];

package/dist/judge.d.ts

@@ -9,5 +9,19 @@ import type { TileWords } from "./tileWords.ts";
  * through it a word (`readWilds`); where none does, the grid is judged as
  * laid and the run is named with its `*`. `rules` says whether the diagonals
  * are read (`GridRules`).
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param words - The loaded native language word list and tile mappings.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns A GRID JUDGED AGAINST ITS LANGUAGE'S LIST, the one way the solo game, each seat of a pass-and-play game and the server's check all ask it: a run is a word when its tiles spell one the list holds (`wordOf`, so a wild reads as the letter or kana it was given), and a run that is not is named as it reads. A wild given no letter reads as whichever letter makes every run through it a word (`readWilds`); where none does, the grid is judged as laid and the run is named with its `*`. `rules` says whether the diagonals are read (`GridRules`).
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { judgeWithWords } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(judgeWithWords(tiles,words));
+ * ```
  */
 export declare function judgeWithWords(tiles: Tiles, words: TileWords, rules?: GridRules): GridVerdict;

package/dist/judge.js

@@ -9,6 +9,20 @@ import { readWilds } from "./wilds.js";
  * through it a word (`readWilds`); where none does, the grid is judged as
  * laid and the run is named with its `*`. `rules` says whether the diagonals
  * are read (`GridRules`).
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param words - The loaded native language word list and tile mappings.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns A GRID JUDGED AGAINST ITS LANGUAGE'S LIST, the one way the solo game, each seat of a pass-and-play game and the server's check all ask it: a run is a word when its tiles spell one the list holds (`wordOf`, so a wild reads as the letter or kana it was given), and a run that is not is named as it reads. A wild given no letter reads as whichever letter makes every run through it a word (`readWilds`); where none does, the grid is judged as laid and the run is named with its `*`. `rules` says whether the diagonals are read (`GridRules`).
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { judgeWithWords } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(judgeWithWords(tiles,words));
+ * ```
  */
 export function judgeWithWords(tiles, words, rules = {}) {
     const read = readWilds(tiles, words, rules) ?? tiles;

package/dist/kana.d.ts

@@ -12,14 +12,36 @@
  * form: は then ん is はん, ばん and ぱん at once. The word list is stored
  * already read this way (`scripts/word-lists-ja.mjs` folds it with the same
  * table), so checking a line is one lookup.
+ *
+ * @example
+ * ```ts
+ * import { BASE_KANA } from "@johnmorrisdotca/kumimoji";
+ * console.log(BASE_KANA);
+ * ```
  */
 export declare const BASE_KANA = "\u3042\u3044\u3046\u3048\u304A\u304B\u304D\u304F\u3051\u3053\u3055\u3057\u3059\u305B\u305D\u305F\u3061\u3064\u3066\u3068\u306A\u306B\u306C\u306D\u306E\u306F\u3072\u3075\u3078\u307B\u307E\u307F\u3080\u3081\u3082\u3084\u3086\u3088\u3089\u308A\u308B\u308C\u308D\u308F\u3093";
-/** The tile a kana is played with, or null for anything that is not hiragana (ー, katakana, a letter). */
+/** The tile a kana is played with, or null for anything that is not hiragana (ー, katakana, a letter).
+ *
+ * @param kana - The hiragana reading to map to a base tile.
+ * @returns The tile a kana is played with, or null for anything that is not hiragana (ー, katakana, a letter).
+ * @example
+ * ```ts
+ * import { tileKana } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(tileKana("が"));
+ * ```
+ */
 export declare function tileKana(kana: string): string | null;
 /**
  * WHAT A TILE SHOWS SMALL IN ITS CORNER: the other ways it is commonly played
  * (John, 2026-09-28: "the tiles like Yu can show the regular and small version
  * in that tile to show its versatility"). Only the forms a player reaches for;
  * the rare ones (ぁ, ゎ, ゔ) still play, and the rules say so.
+ *
+ * @example
+ * ```ts
+ * import { CORNER_FORMS } from "@johnmorrisdotca/kumimoji";
+ * console.log(CORNER_FORMS);
+ * ```
  */
 export declare const CORNER_FORMS: Readonly<Record<string, string>>;

package/dist/kana.js

@@ -12,12 +12,28 @@
  * form: は then ん is はん, ばん and ぱん at once. The word list is stored
  * already read this way (`scripts/word-lists-ja.mjs` folds it with the same
  * table), so checking a line is one lookup.
+ *
+ * @example
+ * ```ts
+ * import { BASE_KANA } from "@johnmorrisdotca/kumimoji";
+ * console.log(BASE_KANA);
+ * ```
  */
 export const BASE_KANA = "あいうえおかきくけこさしすせそたちつてとなにぬねのはひふへほまみむめもやゆよらりるれろわん";
 const SMALL_AND_OLD = {
     ぁ: "あ", ぃ: "い", ぅ: "う", ぇ: "え", ぉ: "お", っ: "つ", ゃ: "や", ゅ: "ゆ", ょ: "よ", ゎ: "わ", ゕ: "か", ゖ: "け", を: "お", ゐ: "い", ゑ: "え",
 };
-/** The tile a kana is played with, or null for anything that is not hiragana (ー, katakana, a letter). */
+/** The tile a kana is played with, or null for anything that is not hiragana (ー, katakana, a letter).
+ *
+ * @param kana - The hiragana reading to map to a base tile.
+ * @returns The tile a kana is played with, or null for anything that is not hiragana (ー, katakana, a letter).
+ * @example
+ * ```ts
+ * import { tileKana } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(tileKana("が"));
+ * ```
+ */
 export function tileKana(kana) {
     const bare = kana.normalize("NFD").replace(/[゙゚]/gu, "").normalize("NFC");
     const base = SMALL_AND_OLD[bare] ?? bare;
@@ -28,6 +44,12 @@ export function tileKana(kana) {
  * (John, 2026-09-28: "the tiles like Yu can show the regular and small version
  * in that tile to show its versatility"). Only the forms a player reaches for;
  * the rare ones (ぁ, ゎ, ゔ) still play, and the rules say so.
+ *
+ * @example
+ * ```ts
+ * import { CORNER_FORMS } from "@johnmorrisdotca/kumimoji";
+ * console.log(CORNER_FORMS);
+ * ```
  */
 export const CORNER_FORMS = {
     か: "が", き: "ぎ", く: "ぐ", け: "げ", こ: "ご",

package/dist/kumimoji.types.d.ts

@@ -1,16 +1,60 @@
-/** How much of the set a game's bag holds: a short game, half the set, or all of it. */
+/** How much of the set a game's bag holds: a short game, half the set, or all of it.
+ *
+ * @example
+ * ```ts
+ * import type { KumimojiLength } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: KumimojiLength = "short";
+ * console.log(value);
+ * ```
+ */
 export type KumimojiLength = "short" | "medium" | "full";
-/** How many of the bag's tiles are wild: easy the most, hard none (`KUMIMOJI_WILDS`). */
+/** How many of the bag's tiles are wild: easy the most, hard none (`KUMIMOJI_WILDS`).
+ *
+ * @example
+ * ```ts
+ * import type { KumimojiLevel } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: KumimojiLevel = "hard";
+ * console.log(value);
+ * ```
+ */
 export type KumimojiLevel = "easy" | "medium" | "hard";
-/** The language of the tiles and of the word list they are judged by. */
+/** The language of the tiles and of the word list they are judged by.
+ *
+ * @example
+ * ```ts
+ * import type { KumimojiLanguage } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: KumimojiLanguage = "japanese";
+ * console.log(value);
+ * ```
+ */
 export type KumimojiLanguage = "english" | "japanese";
-/** How far the player has turned the table to look at it: quarter turns clockwise, 0 to 3. The view alone; the grid never turns. */
+/** How far the player has turned the table to look at it: quarter turns clockwise, 0 to 3. The view alone; the grid never turns.
+ *
+ * @example
+ * ```ts
+ * import type { Turn } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: Turn = 1;
+ * console.log(value);
+ * ```
+ */
 export type Turn = 0 | 1 | 2 | 3;
 /**
  * WHAT A KUMIMOJI WAS SET UP AS, beyond its hand and level: the choices that
  * make one game a different game from another at the same seed, carried
  * together wherever a game is made, checked, kept or raced. Each is optional,
  * and its absence is the default: Short, English, one set, no diagonals.
+ *
+ * @example
+ * ```ts
+ * import type { KumimojiOptions } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: KumimojiOptions = {language:"english",diagonals:false};
+ * console.log(value);
+ * ```
  */
 export type KumimojiOptions = {
     gameLength?: KumimojiLength;
@@ -24,7 +68,16 @@ 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.
+ *
+ * @example
+ * ```ts
+ * import type { KumimojiCheck } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: KumimojiCheck = {ok:false,reason:"Not a finished grid"};
+ * console.log(value);
+ * ```
+ */
 export type KumimojiCheck = {
     ok: true;
 } | {
@@ -35,6 +88,18 @@ export type KumimojiCheck = {
  * A GAME DEALT (`generateKumimoji`): the bag, in the order its tiles come out,
  * as one string of tile codes (`*` a wild), and one finished grid of those
  * tiles that proves the bag can be finished, never shown to the player.
+ *
+ * @example
+ * ```ts
+ * import { generateKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import type { KumimojiDeal } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const dealt = generateKumimoji(3,"hard",44);
+ * const value: KumimojiDeal = dealt;
+ * console.log(value);
+ * ```
  */
 export type KumimojiDeal = {
     kind: "kumimoji";