@johnmorrisdotca/kumimoji 1.2.2 → 1.3.0

package/dist/play.d.ts

@@ -12,6 +12,16 @@ import { type GridVerdict, type Tiles } from "./grid.ts";
  * a game the same for everybody at a seed, trades and all, and lets a kept
  * game be checked: what is held — hand and table — is exactly what was taken,
  * less what was given back.
+ *
+ * @example
+ * ```ts
+ * import { deal } from "@johnmorrisdotca/kumimoji";
+ * import type { TilePlay } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * const value: TilePlay = play;
+ * console.log(value);
+ * ```
  */
 export type TilePlay = {
     /** The tiles in the order they come out: the puzzle's givens. */
@@ -25,39 +35,225 @@ export type TilePlay = {
     /** The hand, in the order the player keeps it. */
     hand: readonly string[];
 };
-/** The opening hand: the first `handSize` tiles of the bag, and an empty table. */
+/** The opening hand: the first `handSize` tiles of the bag, and an empty table.
+ *
+ * @param bag - The original bag in draw order.
+ * @param handSize - The initial number of tiles to draw.
+ * @returns The opening hand: the first `handSize` tiles of the bag, and an empty table.
+ * @example
+ * ```ts
+ * import { deal } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(deal("catdog",3));
+ * ```
+ */
 export declare function deal(bag: string, handSize: number): TilePlay;
-/** How many tiles are still in the bag. */
+/** How many tiles are still in the bag.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @returns How many tiles are still in the bag.
+ * @example
+ * ```ts
+ * import { deal, tilesLeft } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(tilesLeft(play));
+ * ```
+ */
 export declare function tilesLeft(play: TilePlay): number;
-/** A tile from the hand onto an empty square. */
+/** A tile from the hand onto an empty square.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param handAt - The zero-based index of a tile in hand.
+ * @param square - The row,column square name.
+ * @returns A tile from the hand onto an empty square.
+ * @example
+ * ```ts
+ * import { deal, placeFromHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * const play = deal("catdog",3);
+ * console.log(placeFromHand(play,0,"0,0").tiles.size);
+ * ```
+ */
 export declare function placeFromHand(play: TilePlay, handAt: number, square: string): TilePlay;
-/** Give a hand tile its chosen reading, without changing which physical tile it is. */
+/** Give a hand tile its chosen reading, without changing which physical tile it is.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param handAt - The zero-based index of a tile in hand.
+ * @param face - The visible reading to assign to a wild tile.
+ * @returns Give a hand tile its chosen reading, without changing which physical tile it is.
+ * @example
+ * ```ts
+ * import { assignHandTile, deal } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(assignHandTile(deal("*atdog",3),0,"c").hand);
+ * ```
+ */
 export declare function assignHandTile(play: TilePlay, handAt: number, face: string): TilePlay;
-/** Give a tile on the table its chosen reading, without changing its square. */
+/** Give a tile on the table its chosen reading, without changing its square.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param square - The row,column square name.
+ * @param face - The visible reading to assign to a wild tile.
+ * @returns Give a tile on the table its chosen reading, without changing its square.
+ * @example
+ * ```ts
+ * import { assignTableTile, deal, placeFromHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(assignTableTile(placeFromHand(deal("*atdog",3),0,"0,0"),"0,0","c").tiles);
+ * ```
+ */
 export declare function assignTableTile(play: TilePlay, square: string, face: string): TilePlay;
-/** A tile on the table to another square: to an empty one it moves, onto a tile the two change places. */
+/** A tile on the table to another square: to an empty one it moves, onto a tile the two change places.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param from - The source square or seat index.
+ * @param to - The destination square.
+ * @returns A tile on the table to another square: to an empty one it moves, onto a tile the two change places.
+ * @example
+ * ```ts
+ * import { deal, moveOnTable, placeFromHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * const laid = placeFromHand(deal("catdog",3),0,"0,0");
+ * console.log(moveOnTable(laid,"0,0","1,0").tiles);
+ * ```
+ */
 export declare function moveOnTable(play: TilePlay, from: string, to: string): TilePlay;
-/** A tile from the hand onto a square that holds one: they change places, the table's tile going to the hand where the other was. */
+/** A tile from the hand onto a square that holds one: they change places, the table's tile going to the hand where the other was.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param handAt - The zero-based index of a tile in hand.
+ * @param square - The row,column square name.
+ * @returns A tile from the hand onto a square that holds one: they change places, the table's tile going to the hand where the other was.
+ * @example
+ * ```ts
+ * import { deal, placeFromHand, swapWithHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const laid = placeFromHand(deal("catdog",3),0,"0,0");
+ * console.log(swapWithHand(laid,0,"0,0").hand);
+ * ```
+ */
 export declare function swapWithHand(play: TilePlay, handAt: number, square: string): TilePlay;
-/** A tile on the table back to the end of the hand. */
+/** A tile on the table back to the end of the hand.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param square - The row,column square name.
+ * @returns A tile on the table back to the end of the hand.
+ * @example
+ * ```ts
+ * import { deal, liftToHand, placeFromHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const laid = placeFromHand(deal("catdog",3),0,"0,0");
+ * console.log(liftToHand(laid,"0,0").hand);
+ * ```
+ */
 export declare function liftToHand(play: TilePlay, square: string): TilePlay;
-/** Every tile on the table back to the hand. */
+/** Every tile on the table back to the hand.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @returns Every tile on the table back to the hand.
+ * @example
+ * ```ts
+ * import { deal, liftAll, placeFromHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const laid = placeFromHand(deal("catdog",3),0,"0,0");
+ * console.log(liftAll(laid).hand);
+ * ```
+ */
 export declare function liftAll(play: TilePlay): TilePlay;
 /**
  * The hand in order (John, 2026-09-28: "it gets sorted for letters
  * alphabetically"): English A to Z, Japanese あいうえお, which is the order
  * of the kana's tile codes, and the wilds last as they came.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @returns The hand in order (John, 2026-09-28: "it gets sorted for letters alphabetically"): English A to Z, Japanese あいうえお, which is the order of the kana's tile codes, and the wilds last as they came.
+ * @example
+ * ```ts
+ * import { deal, sortHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(sortHand(play).hand);
+ * ```
  */
 export declare function sortHand(play: TilePlay): TilePlay;
-/** Whether Draw may be pressed: the hand used, the grid sound, and a tile left to draw. */
+/** Whether Draw may be pressed: the hand used, the grid sound, and a tile left to draw.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param verdict - The native word and connectivity verdict for this grid.
+ * @returns Whether Draw may be pressed: the hand used, the grid sound, and a tile left to draw.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { deal, judgeWithWords, mayDraw } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const verdict = judgeWithWords(new Map([["0,0","c"],["0,1","a"],["0,2","t"]]),words);
+ * console.log(mayDraw(play,verdict));
+ * ```
+ */
 export declare function mayDraw(play: TilePlay, verdict: GridVerdict): boolean;
-/** The next tile or tiles out of the bag into the hand. */
+/** The next tile or tiles out of the bag into the hand.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param count - The number of tiles to draw.
+ * @returns The next tile or tiles out of the bag into the hand.
+ * @example
+ * ```ts
+ * import { deal, draw } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(draw(play,1).hand);
+ * ```
+ */
 export declare function draw(play: TilePlay, count?: number): TilePlay;
-/** Whether a trade may be made: the bag holds as many as a trade takes. */
+/** Whether a trade may be made: the bag holds as many as a trade takes.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @returns Whether a trade may be made: the bag holds as many as a trade takes.
+ * @example
+ * ```ts
+ * import { deal, mayTrade } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(mayTrade(play));
+ * ```
+ */
 export declare function mayTrade(play: TilePlay): boolean;
-/** One tile from the hand to the bottom of the bag, and the next three out of it. */
+/** One tile from the hand to the bottom of the bag, and the next three out of it.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param handAt - The zero-based index of a tile in hand.
+ * @returns One tile from the hand to the bottom of the bag, and the next three out of it.
+ * @example
+ * ```ts
+ * import { deal, trade } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(trade(play,0).hand);
+ * ```
+ */
 export declare function trade(play: TilePlay, handAt: number): TilePlay;
-/** Whether the game is over: the bag empty, the hand used, and the grid sound. */
+/** Whether the game is over: the bag empty, the hand used, and the grid sound.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param verdict - The native word and connectivity verdict for this grid.
+ * @returns Whether the game is over: the bag empty, the hand used, and the grid sound.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { deal, isFinished, judgeWithWords } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const verdict = judgeWithWords(new Map([["0,0","c"],["0,1","a"],["0,2","t"]]),words);
+ * console.log(isFinished(play,verdict));
+ * ```
+ */
 export declare function isFinished(play: TilePlay, verdict: GridVerdict): boolean;
 /**
  * A GAME KEPT half way, as one string (`PuzzleRun.progress`): how many tiles
@@ -65,9 +261,30 @@ export declare function isFinished(play: TilePlay, verdict: GridVerdict): boolea
  * (`encodeGrid`), as `12:q:ae:cat/2o/2w`. The bag is the puzzle's own, from
  * its seed, so it is not written again, and where on the table the grid stood
  * is the view's and not kept.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @returns A GAME KEPT half way, as one string (`PuzzleRun.progress`): how many tiles were taken, the tiles traded back, the hand in its order and the grid (`encodeGrid`), as `12:q:ae:cat/2o/2w`. The bag is the puzzle's own, from its seed, so it is not written again, and where on the table the grid stood is the view's and not kept.
+ * @example
+ * ```ts
+ * import { deal, encodeTileProgress } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(encodeTileProgress(play));
+ * ```
  */
 export declare function encodeTileProgress(play: TilePlay): string;
-/** The parts of a kept game, or null for a string that is not one: its shape only, with no bag to check it against. */
+/** The parts of a kept game, or null for a string that is not one: its shape only, with no bag to check it against.
+ *
+ * @param code - The encoded grid or progress text.
+ * @returns The parts of a kept game, or null for a string that is not one: its shape only, with no bag to check it against.
+ * @example
+ * ```ts
+ * import { deal, encodeTileProgress, readTileProgress } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(readTileProgress(encodeTileProgress(play)));
+ * ```
+ */
 export declare function readTileProgress(code: string): {
     taken: number;
     returned: string;
@@ -79,5 +296,20 @@ export declare function readTileProgress(code: string): {
  * to it: every tile held — hand and table — must be one taken from the bag
  * and not given back. Null opens the game fresh rather than on a grid that
  * never came out of this bag.
+ *
+ * @param code - The encoded grid or progress text.
+ * @param bag - The original bag in draw order.
+ * @param language - The English or Japanese tile language.
+ * @returns A kept game opened again on its own bag, or null where it does not belong to it: every tile held — hand and table — must be one taken from the bag and not given back. Null opens the game fresh rather than on a grid that never came out of this bag.
+ * @example
+ * ```ts
+ * import { deal, decodeTileProgress, encodeTileProgress } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const bag = "catdogsun";
+ * console.log(decodeTileProgress(encodeTileProgress(play),play.bag));
+ * ```
  */
 export declare function decodeTileProgress(code: string, bag: string, language?: "english" | "japanese"): TilePlay | null;

package/dist/play.js

@@ -2,12 +2,34 @@ import { decodeGrid, encodeGrid, lettersOf, sameLetters } from "./grid.js";
 import { tileFace } from "./tileFace.js";
 import { KUMIMOJI_DRAW, KUMIMOJI_TRADE } from "./tiles.constants.js";
 import { tileWords } from "./tileWords.js";
-/** The opening hand: the first `handSize` tiles of the bag, and an empty table. */
+/** The opening hand: the first `handSize` tiles of the bag, and an empty table.
+ *
+ * @param bag - The original bag in draw order.
+ * @param handSize - The initial number of tiles to draw.
+ * @returns The opening hand: the first `handSize` tiles of the bag, and an empty table.
+ * @example
+ * ```ts
+ * import { deal } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(deal("catdog",3));
+ * ```
+ */
 export function deal(bag, handSize) {
     const taken = Math.min(handSize, bag.length);
     return { bag, returned: "", taken, tiles: new Map(), hand: [...bag.slice(0, taken)] };
 }
-/** How many tiles are still in the bag. */
+/** How many tiles are still in the bag.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @returns How many tiles are still in the bag.
+ * @example
+ * ```ts
+ * import { deal, tilesLeft } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(tilesLeft(play));
+ * ```
+ */
 export function tilesLeft(play) {
     return play.bag.length + play.returned.length - play.taken;
 }
@@ -16,14 +38,40 @@ function withTiles(play, change) {
     change(tiles);
     return tiles;
 }
-/** A tile from the hand onto an empty square. */
+/** A tile from the hand onto an empty square.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param handAt - The zero-based index of a tile in hand.
+ * @param square - The row,column square name.
+ * @returns A tile from the hand onto an empty square.
+ * @example
+ * ```ts
+ * import { deal, placeFromHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * const play = deal("catdog",3);
+ * console.log(placeFromHand(play,0,"0,0").tiles.size);
+ * ```
+ */
 export function placeFromHand(play, handAt, square) {
     const letter = play.hand[handAt];
     if (letter === undefined || play.tiles.has(square))
         return play;
     return { ...play, tiles: withTiles(play, (tiles) => tiles.set(square, letter)), hand: play.hand.filter((_, at) => at !== handAt) };
 }
-/** Give a hand tile its chosen reading, without changing which physical tile it is. */
+/** Give a hand tile its chosen reading, without changing which physical tile it is.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param handAt - The zero-based index of a tile in hand.
+ * @param face - The visible reading to assign to a wild tile.
+ * @returns Give a hand tile its chosen reading, without changing which physical tile it is.
+ * @example
+ * ```ts
+ * import { assignHandTile, deal } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(assignHandTile(deal("*atdog",3),0,"c").hand);
+ * ```
+ */
 export function assignHandTile(play, handAt, face) {
     if (play.hand[handAt] === undefined || face.length !== 1)
         return play;
@@ -31,13 +79,40 @@ export function assignHandTile(play, handAt, face) {
     hand[handAt] = face;
     return { ...play, hand };
 }
-/** Give a tile on the table its chosen reading, without changing its square. */
+/** Give a tile on the table its chosen reading, without changing its square.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param square - The row,column square name.
+ * @param face - The visible reading to assign to a wild tile.
+ * @returns Give a tile on the table its chosen reading, without changing its square.
+ * @example
+ * ```ts
+ * import { assignTableTile, deal, placeFromHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(assignTableTile(placeFromHand(deal("*atdog",3),0,"0,0"),"0,0","c").tiles);
+ * ```
+ */
 export function assignTableTile(play, square, face) {
     if (!play.tiles.has(square) || face.length !== 1)
         return play;
     return { ...play, tiles: withTiles(play, (tiles) => tiles.set(square, face)) };
 }
-/** A tile on the table to another square: to an empty one it moves, onto a tile the two change places. */
+/** A tile on the table to another square: to an empty one it moves, onto a tile the two change places.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param from - The source square or seat index.
+ * @param to - The destination square.
+ * @returns A tile on the table to another square: to an empty one it moves, onto a tile the two change places.
+ * @example
+ * ```ts
+ * import { deal, moveOnTable, placeFromHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * const laid = placeFromHand(deal("catdog",3),0,"0,0");
+ * console.log(moveOnTable(laid,"0,0","1,0").tiles);
+ * ```
+ */
 export function moveOnTable(play, from, to) {
     const moving = play.tiles.get(from);
     if (from === to || moving === undefined)
@@ -53,7 +128,20 @@ export function moveOnTable(play, from, to) {
         }),
     };
 }
-/** A tile from the hand onto a square that holds one: they change places, the table's tile going to the hand where the other was. */
+/** A tile from the hand onto a square that holds one: they change places, the table's tile going to the hand where the other was.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param handAt - The zero-based index of a tile in hand.
+ * @param square - The row,column square name.
+ * @returns A tile from the hand onto a square that holds one: they change places, the table's tile going to the hand where the other was.
+ * @example
+ * ```ts
+ * import { deal, placeFromHand, swapWithHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const laid = placeFromHand(deal("catdog",3),0,"0,0");
+ * console.log(swapWithHand(laid,0,"0,0").hand);
+ * ```
+ */
 export function swapWithHand(play, handAt, square) {
     const letter = play.hand[handAt];
     const lifted = play.tiles.get(square);
@@ -63,14 +151,37 @@ export function swapWithHand(play, handAt, square) {
     hand[handAt] = lifted;
     return { ...play, tiles: withTiles(play, (tiles) => tiles.set(square, letter)), hand };
 }
-/** A tile on the table back to the end of the hand. */
+/** A tile on the table back to the end of the hand.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param square - The row,column square name.
+ * @returns A tile on the table back to the end of the hand.
+ * @example
+ * ```ts
+ * import { deal, liftToHand, placeFromHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const laid = placeFromHand(deal("catdog",3),0,"0,0");
+ * console.log(liftToHand(laid,"0,0").hand);
+ * ```
+ */
 export function liftToHand(play, square) {
     const letter = play.tiles.get(square);
     if (letter === undefined)
         return play;
     return { ...play, tiles: withTiles(play, (tiles) => tiles.delete(square)), hand: [...play.hand, letter] };
 }
-/** Every tile on the table back to the hand. */
+/** Every tile on the table back to the hand.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @returns Every tile on the table back to the hand.
+ * @example
+ * ```ts
+ * import { deal, liftAll, placeFromHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const laid = placeFromHand(deal("catdog",3),0,"0,0");
+ * console.log(liftAll(laid).hand);
+ * ```
+ */
 export function liftAll(play) {
     return { ...play, tiles: new Map(), hand: [...play.hand, ...play.tiles.values()] };
 }
@@ -78,27 +189,87 @@ export function liftAll(play) {
  * The hand in order (John, 2026-09-28: "it gets sorted for letters
  * alphabetically"): English A to Z, Japanese あいうえお, which is the order
  * of the kana's tile codes, and the wilds last as they came.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @returns The hand in order (John, 2026-09-28: "it gets sorted for letters alphabetically"): English A to Z, Japanese あいうえお, which is the order of the kana's tile codes, and the wilds last as they came.
+ * @example
+ * ```ts
+ * import { deal, sortHand } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(sortHand(play).hand);
+ * ```
  */
 export function sortHand(play) {
     const hand = [...play.hand].sort((a, b) => Number(tileFace(a).wild) - Number(tileFace(b).wild) || (tileFace(a).wild ? 0 : a < b ? -1 : a > b ? 1 : 0));
     return { ...play, hand };
 }
-/** Whether Draw may be pressed: the hand used, the grid sound, and a tile left to draw. */
+/** Whether Draw may be pressed: the hand used, the grid sound, and a tile left to draw.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param verdict - The native word and connectivity verdict for this grid.
+ * @returns Whether Draw may be pressed: the hand used, the grid sound, and a tile left to draw.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { deal, judgeWithWords, mayDraw } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const verdict = judgeWithWords(new Map([["0,0","c"],["0,1","a"],["0,2","t"]]),words);
+ * console.log(mayDraw(play,verdict));
+ * ```
+ */
 export function mayDraw(play, verdict) {
     return play.hand.length === 0 && verdict.sound && tilesLeft(play) > 0;
 }
-/** The next tile or tiles out of the bag into the hand. */
+/** The next tile or tiles out of the bag into the hand.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param count - The number of tiles to draw.
+ * @returns The next tile or tiles out of the bag into the hand.
+ * @example
+ * ```ts
+ * import { deal, draw } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(draw(play,1).hand);
+ * ```
+ */
 export function draw(play, count = KUMIMOJI_DRAW) {
     const coming = (play.bag + play.returned).slice(play.taken, play.taken + count);
     if (coming.length === 0)
         return play;
     return { ...play, taken: play.taken + coming.length, hand: [...play.hand, ...coming] };
 }
-/** Whether a trade may be made: the bag holds as many as a trade takes. */
+/** Whether a trade may be made: the bag holds as many as a trade takes.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @returns Whether a trade may be made: the bag holds as many as a trade takes.
+ * @example
+ * ```ts
+ * import { deal, mayTrade } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(mayTrade(play));
+ * ```
+ */
 export function mayTrade(play) {
     return tilesLeft(play) >= KUMIMOJI_TRADE.take;
 }
-/** One tile from the hand to the bottom of the bag, and the next three out of it. */
+/** One tile from the hand to the bottom of the bag, and the next three out of it.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param handAt - The zero-based index of a tile in hand.
+ * @returns One tile from the hand to the bottom of the bag, and the next three out of it.
+ * @example
+ * ```ts
+ * import { deal, trade } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(trade(play,0).hand);
+ * ```
+ */
 export function trade(play, handAt) {
     const letter = play.hand[handAt];
     if (letter === undefined || !mayTrade(play))
@@ -107,7 +278,22 @@ export function trade(play, handAt) {
     const coming = (play.bag + returned).slice(play.taken, play.taken + KUMIMOJI_TRADE.take);
     return { ...play, returned, taken: play.taken + coming.length, hand: [...play.hand.filter((_, at) => at !== handAt), ...coming] };
 }
-/** Whether the game is over: the bag empty, the hand used, and the grid sound. */
+/** Whether the game is over: the bag empty, the hand used, and the grid sound.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param verdict - The native word and connectivity verdict for this grid.
+ * @returns Whether the game is over: the bag empty, the hand used, and the grid sound.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { deal, isFinished, judgeWithWords } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const verdict = judgeWithWords(new Map([["0,0","c"],["0,1","a"],["0,2","t"]]),words);
+ * console.log(isFinished(play,verdict));
+ * ```
+ */
 export function isFinished(play, verdict) {
     return play.hand.length === 0 && tilesLeft(play) === 0 && verdict.sound;
 }
@@ -117,11 +303,32 @@ export function isFinished(play, verdict) {
  * (`encodeGrid`), as `12:q:ae:cat/2o/2w`. The bag is the puzzle's own, from
  * its seed, so it is not written again, and where on the table the grid stood
  * is the view's and not kept.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @returns A GAME KEPT half way, as one string (`PuzzleRun.progress`): how many tiles were taken, the tiles traded back, the hand in its order and the grid (`encodeGrid`), as `12:q:ae:cat/2o/2w`. The bag is the puzzle's own, from its seed, so it is not written again, and where on the table the grid stood is the view's and not kept.
+ * @example
+ * ```ts
+ * import { deal, encodeTileProgress } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(encodeTileProgress(play));
+ * ```
  */
 export function encodeTileProgress(play) {
     return `${play.taken}:${play.returned}:${play.hand.join("")}:${encodeGrid(play.tiles)}`;
 }
-/** The parts of a kept game, or null for a string that is not one: its shape only, with no bag to check it against. */
+/** The parts of a kept game, or null for a string that is not one: its shape only, with no bag to check it against.
+ *
+ * @param code - The encoded grid or progress text.
+ * @returns The parts of a kept game, or null for a string that is not one: its shape only, with no bag to check it against.
+ * @example
+ * ```ts
+ * import { deal, encodeTileProgress, readTileProgress } from "@johnmorrisdotca/kumimoji";
+ *
+ * const play = deal("catdog",3);
+ * console.log(readTileProgress(encodeTileProgress(play)));
+ * ```
+ */
 export function readTileProgress(code) {
     const parts = code.split(":");
     if (parts.length !== 4)
@@ -139,6 +346,21 @@ export function readTileProgress(code) {
  * to it: every tile held — hand and table — must be one taken from the bag
  * and not given back. Null opens the game fresh rather than on a grid that
  * never came out of this bag.
+ *
+ * @param code - The encoded grid or progress text.
+ * @param bag - The original bag in draw order.
+ * @param language - The English or Japanese tile language.
+ * @returns A kept game opened again on its own bag, or null where it does not belong to it: every tile held — hand and table — must be one taken from the bag and not given back. Null opens the game fresh rather than on a grid that never came out of this bag.
+ * @example
+ * ```ts
+ * import { deal, decodeTileProgress, encodeTileProgress } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * const bag = "catdogsun";
+ * console.log(decodeTileProgress(encodeTileProgress(play),play.bag));
+ * ```
  */
 export function decodeTileProgress(code, bag, language = "english") {
     const read = readTileProgress(code);