@johnmorrisdotca/kumimoji 1.2.1 → 1.3.0

package/dist/generate.js

@@ -29,6 +29,20 @@ import { tileWords } from "./tileWords.js";
  *
  * Deterministic in the seed, like every generator here: two browsers in a
  * race, or one tomorrow, deal the same bag in the same order.
+ *
+ * @param size - The supported initial hand size.
+ * @param level - The difficulty that determines the wildcard allowance.
+ * @param seed - The numeric seed for deterministic deals or random draws.
+ * @param options - Native game, component or presentation options.
+ * @returns MAKING A KUMIMOJI, in the browser, from a seed: the bag the game is played from, in the order its tiles come out.
+ * @example
+ * ```ts
+ * import { generateKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(generateKumimoji(3,"hard",44).givens);
+ * ```
  */
 export function generateKumimoji(size, level, seed, options = {}) {
     const gameLength = options.gameLength ?? "short";

package/dist/grid.d.ts

@@ -11,40 +11,139 @@
  * and COW down from its C. Only
  * where the tiles stand beside one another is written, never where on the
  * table they were, so one grid has one spelling however far it was dragged.
+ *
+ * @example
+ * ```ts
+ * import type { Tiles } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * const value: Tiles = tiles;
+ * console.log(value);
+ * ```
  */
 export type Tiles = ReadonlyMap<string, string>;
-/** 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 declare function squareAt(row: number, col: number): string;
-/** 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 declare function placeOf(square: string): {
     row: number;
     col: number;
 };
-/** The rows and columns a grid's tiles stand within. */
+/** The rows and columns a grid's tiles stand within.
+ *
+ * @example
+ * ```ts
+ * import type { Bounds } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: Bounds = {top:0,left:0,bottom:0,right:2};
+ * console.log(value);
+ * ```
+ */
 export type Bounds = {
     top: number;
     left: number;
     bottom: number;
     right: number;
 };
-/** 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 declare function boundsOf(tiles: Tiles): Bounds | null;
-/** 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 declare function encodeGrid(tiles: Tiles): string;
 /**
  * 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 declare function decodeGrid(code: string): Map<string, string> | null;
-/** 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 declare function lettersOf(letters: Iterable<string>): Map<string, number>;
-/** 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 declare function sameLetters(a: Map<string, number>, b: Map<string, number>): boolean;
 /**
  * THE LINES A RUN MAY LIE ALONG, each read top to bottom (and across, left to
  * right): across and down always, and the two diagonals when the game was set
  * up with Diagonals — down to the right, and down to the left.
+ *
+ * @example
+ * ```ts
+ * import type { RunLine } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: RunLine = "across";
+ * console.log(value);
+ * ```
  */
 export type RunLine = "across" | "down" | "downRight" | "downLeft";
 /**
@@ -52,13 +151,37 @@ export type RunLine = "across" | "down" | "downRight" | "downLeft";
  * 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 declare const DIAGONAL_RUN_LEAST = 3;
-/** How a grid is read: whether its diagonals are (`KumimojiOptions.diagonals`). */
+/** How a grid is read: whether its diagonals are (`KumimojiOptions.diagonals`).
+ *
+ * @example
+ * ```ts
+ * import type { GridRules } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: GridRules = {diagonals:true};
+ * console.log(value);
+ * ```
+ */
 export type GridRules = {
     diagonals?: boolean;
 };
-/** A run of tiles along one line: the word it spells and the squares it stands on, in reading order. */
+/** A run of tiles along one line: the word it spells and the squares it stands on, in reading order.
+ *
+ * @example
+ * ```ts
+ * import type { Run } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: Run = {word:"cat",squares:["0,0","0,1","0,2"],line:"across"};
+ * console.log(value);
+ * ```
+ */
 export type Run = {
     word: string;
     squares: string[];
@@ -68,6 +191,17 @@ export type Run = {
  * 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 declare function runsOf(tiles: Tiles, rules?: GridRules): Run[];
 /**
@@ -76,6 +210,17 @@ export declare function runsOf(tiles: Tiles, rules?: GridRules): Run[];
  * 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 declare function groupsOf(tiles: Tiles, links?: readonly Run[]): string[][];
 /**
@@ -85,6 +230,18 @@ export declare function groupsOf(tiles: Tiles, links?: readonly Run[]): string[]
  * With Diagonals (`rules`), the diagonal runs of three or more are runs too:
  * each must be a word, a misspelt one is marked as any other is, and each
  * joins its tiles (`groupsOf`).
+ *
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { judgeWithWords } from "@johnmorrisdotca/kumimoji";
+ * import type { GridVerdict } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const verdict = judgeWithWords(new Map([["0,0","c"],["0,1","a"],["0,2","t"]]),words);
+ * const value: GridVerdict = verdict;
+ * console.log(value);
+ * ```
  */
 export type GridVerdict = {
     sound: boolean;
@@ -96,5 +253,19 @@ export type GridVerdict = {
     /** The runs that are not words, as spelled, for the line under the table. */
     notWords: readonly string[];
 };
-/** 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 declare function judgeGrid(tiles: Tiles, isWord: (word: string) => boolean, readable?: (word: string) => string, rules?: GridRules): GridVerdict;

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>>;