@johnmorrisdotca/kumimoji 1.2.1 → 1.3.0

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

package/dist/party.d.ts

@@ -17,11 +17,44 @@ import { type TilePlay } from "./play.ts";
  * everybody — and in `partyTurns.ts`: Done, going out, the last round,
  * resigning and who won. Pure, like every rule here: each returns a new game.
  */
-/** The tiles a bag must hold for this many players: a hand each and one round of draws. */
+/** The tiles a bag must hold for this many players: a hand each and one round of draws.
+ *
+ * @param players - The requested player count or current player rows.
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @returns The tiles a bag must hold for this many players: a hand each and one round of draws.
+ * @example
+ * ```ts
+ * import { partyTilesNeeded } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(partyTilesNeeded(2,3));
+ * ```
+ */
 export declare function partyTilesNeeded(players: number, hand: number): number;
-/** Whether a bag of this many tiles can be played by this many: one player can play any bag. */
+/** Whether a bag of this many tiles can be played by this many: one player can play any bag.
+ *
+ * @param players - The requested player count or current player rows.
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @returns Whether a bag of this many tiles can be played by this many: one player can play any bag.
+ * @example
+ * ```ts
+ * import { partyFits } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(partyFits(2,3,12));
+ * ```
+ */
 export declare function partyFits(players: number, hand: number, tiles: number): boolean;
-/** A players count from the address, or 1 (the solo game) for anything that is not two to eight. */
+/** A players count from the address, or 1 (the solo game) for anything that is not two to eight.
+ *
+ * @param value - The unknown setup value to interpret.
+ * @returns A players count from the address, or 1 (the solo game) for anything that is not two to eight.
+ * @example
+ * ```ts
+ * import { partyPlayersAsked } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(partyPlayersAsked("3"));
+ * ```
+ */
 export declare function partyPlayersAsked(value: unknown): number;
 /**
  * The game length a set-up plays at: the one chosen where the bag holds this
@@ -29,25 +62,125 @@ export declare function partyPlayersAsked(value: unknown): number;
  * players comes back when there are fewer again. A Full bag of one set is 144
  * tiles, and eight Classic hands with a round of draws are 96, so there is
  * always one.
+ *
+ * @param players - The requested player count or current player rows.
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param chosen - The selected game length.
+ * @param doubleSet - Whether to use two English tile sets.
+ * @returns The game length a set-up plays at: the one chosen where the bag holds this many players, else the shortest that does, so a choice made for fewer players comes back when there are fewer again. A Full bag of one set is 144 tiles, and eight Classic hands with a round of draws are 96, so there is always one.
+ * @example
+ * ```ts
+ * import { partyLength } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(partyLength(8,11,"short",false));
+ * ```
  */
 export declare function partyLength(players: number, hand: number, chosen: KumimojiLength, doubleSet: boolean): KumimojiLength;
 /**
  * The deal: each player the next hand from the bag in turn, player one first,
  * and every table empty. A seat is a name, or a name and whether a computer
  * plays it; a computer is named "Computer 1", "Computer 2"… in seat order.
+ *
+ * @param settings - The native party setup settings.
+ * @param bag - The original bag in draw order.
+ * @param seats - Local player names and optional computer flags.
+ * @returns The deal: each player the next hand from the bag in turn, player one first, and every table empty. A seat is a name, or a name and whether a computer plays it; a computer is named "Computer 1", "Computer 2"… in seat order.
+ * @example
+ * ```ts
+ * import { startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * console.log(startParty(settings,bag,["Seat 1","Seat 2"]).players.length);
+ * ```
  */
 export declare function startParty(settings: PartySettings, bag: string, seats: readonly (string | PartySeat)[]): PartyGame;
-/** The name a new computer takes: "Computer" and the lowest number no player at the table already goes by. */
+/** The name a new computer takes: "Computer" and the lowest number no player at the table already goes by.
+ *
+ * @param players - The requested player count or current player rows.
+ * @returns The name a new computer takes: "Computer" and the lowest number no player at the table already goes by.
+ * @example
+ * ```ts
+ * import { computerName, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(computerName(game.players));
+ * ```
+ */
 export declare function computerName(players: readonly PartyPlayer[]): string;
-/** Whether a computer plays this seat. */
+/** Whether a computer plays this seat.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns Whether a computer plays this seat.
+ * @example
+ * ```ts
+ * import { isComputer, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(isComputer(game,0));
+ * ```
+ */
 export declare function isComputer(game: PartyGame, at: number): boolean;
-/** A table's tiles as one string in order, wherever they stand: what a turn compares to see whether anything was laid or lifted. */
+/** A table's tiles as one string in order, wherever they stand: what a turn compares to see whether anything was laid or lifted.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @returns A table's tiles as one string in order, wherever they stand: what a turn compares to see whether anything was laid or lifted.
+ * @example
+ * ```ts
+ * import { tableTally } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(tableTally(tiles));
+ * ```
+ */
 export declare function tableTally(tiles: Tiles): string;
-/** A name as kept: trimmed, one line, and no longer than a line holds. */
+/** A name as kept: trimmed, one line, and no longer than a line holds.
+ *
+ * @param name - The local player name to tidy.
+ * @returns A name as kept: trimmed, one line, and no longer than a line holds.
+ * @example
+ * ```ts
+ * import { tidyName } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(tidyName("  Seat  1  "));
+ * ```
+ */
 export declare function tidyName(name: string): string;
-/** What a player is called: their name, or "Player 2". */
+/** What a player is called: their name, or "Player 2".
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @returns What a player is called: their name, or "Player 2".
+ * @example
+ * ```ts
+ * import { nameOf, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(nameOf(game,0));
+ * ```
+ */
 export declare function nameOf(game: PartyGame, at: number): string;
-/** The player whose turn it is, as the solo game's moves take a game: the shared bag, and their own hand and table. */
+/** The player whose turn it is, as the solo game's moves take a game: the shared bag, and their own hand and table.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns The player whose turn it is, as the solo game's moves take a game: the shared bag, and their own hand and table.
+ * @example
+ * ```ts
+ * import { seatPlay, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(seatPlay(game));
+ * ```
+ */
 export declare function seatPlay(game: PartyGame): TilePlay;
 /**
  * ONE TRADE A TURN. John, 2026-09-29, after a player traded over and over and
@@ -56,26 +189,120 @@ export declare function seatPlay(game: PartyGame): TilePlay;
  * takes three, so trading without end lets one player take the bag from the
  * others. After a trade the player may still lay, lift and draw, and press
  * Done; the next trade is on their next turn.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns ONE TRADE A TURN. John, 2026-09-29, after a player traded over and over and built up a hand: "if they swap tiles … give them a chance to lay some tiles but cannot ask for another swap until next turn." A trade gives one tile and takes three, so trading without end lets one player take the bag from the others. After a trade the player may still lay, lift and draw, and press Done; the next trade is on their next turn.
+ * @example
+ * ```ts
+ * import { mayTradeThisTurn, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(mayTradeThisTurn(game));
+ * ```
  */
 export declare function mayTradeThisTurn(game: PartyGame): boolean;
-/** A move made on `seatPlay` put back: the bag as it left it, and the hand and table to the player whose turn it is. A second trade in one turn is refused, the game given back as it was. */
+/** A move made on `seatPlay` put back: the bag as it left it, and the hand and table to the player whose turn it is. A second trade in one turn is refused, the game given back as it was.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param play - The current immutable solo-game progress.
+ * @returns A move made on `seatPlay` put back: the bag as it left it, and the hand and table to the player whose turn it is. A second trade in one turn is refused, the game given back as it was.
+ * @example
+ * ```ts
+ * import { seatPlay, startParty, withSeatPlay } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(withSeatPlay(game,seatPlay(game)).taken);
+ * ```
+ */
 export declare function withSeatPlay(game: PartyGame, play: TilePlay): PartyGame;
-/** Tiles still in the shared bag. */
+/** Tiles still in the shared bag.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns Tiles still in the shared bag.
+ * @example
+ * ```ts
+ * import { partyTilesLeft, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(partyTilesLeft(game));
+ * ```
+ */
 export declare function partyTilesLeft(game: PartyGame): number;
-/** The players still in — not resigned — by place, in turn order. Somebody who went out is still in until the game ends. */
+/** The players still in — not resigned — by place, in turn order. Somebody who went out is still in until the game ends.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns The players still in — not resigned — by place, in turn order. Somebody who went out is still in until the game ends.
+ * @example
+ * ```ts
+ * import { startParty, stillIn } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(stillIn(game));
+ * ```
+ */
 export declare function stillIn(game: PartyGame): number[];
-/** The next player still in after `from`, round the table; `from` itself when nobody else is. */
+/** The next player still in after `from`, round the table; `from` itself when nobody else is.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param from - The source square or seat index.
+ * @returns The next player still in after `from`, round the table; `from` itself when nobody else is.
+ * @example
+ * ```ts
+ * import { nextIn, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(nextIn(game,0));
+ * ```
+ */
 export declare function nextIn(game: PartyGame, from: number): number;
 /**
  * Whether Draw may be pressed: the hand of the player whose turn it is used,
  * their grid sound, and a tile in the bag for every player still in. Never in
  * the last round, when the bag already holds fewer than that.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param verdict - The native word and connectivity verdict for this grid.
+ * @returns Whether Draw may be pressed: the hand of the player whose turn it is used, their grid sound, and a tile in the bag for every player still in. Never in the last round, when the bag already holds fewer than that.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { judgeWithWords, mayDrawAll, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const verdict = judgeWithWords(new Map([["0,0","c"],["0,1","a"],["0,2","t"]]),words);
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(mayDrawAll(game,verdict));
+ * ```
  */
 export declare function mayDrawAll(game: PartyGame, verdict: GridVerdict): boolean;
 /**
  * DRAW: every player still in takes one tile, in turn order from the one who
  * pressed it — the race game's rule that when one player uses their hand,
  * everybody draws.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns DRAW: every player still in takes one tile, in turn order from the one who pressed it — the race game's rule that when one player uses their hand, everybody draws.
+ * @example
+ * ```ts
+ * import { drawAll, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(drawAll(game));
+ * ```
  */
 export declare function drawAll(game: PartyGame): PartyGame;
 /**
@@ -85,7 +312,34 @@ export declare function drawAll(game: PartyGame): PartyGame;
  * screen opens on the table of whoever has just played (the first player's,
  * before anybody has), and a swipe steps round every player in seat order,
  * resigned ones included.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns WHOSE TABLE IS SHOWN. Nothing in a pass-and-play game is secret — John, 2026-09-28: "there are no secrets because they are face up" — so every table and every hand can be looked at by anybody, read-only. The pass screen opens on the table of whoever has just played (the first player's, before anybody has), and a swipe steps round every player in seat order, resigned ones included.
+ * @example
+ * ```ts
+ * import { passViewStart, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(passViewStart(game));
+ * ```
  */
 export declare function passViewStart(game: PartyGame): number;
-/** The player a swipe or an arrow shows next: `by` seats on, round the table. */
+/** The player a swipe or an arrow shows next: `by` seats on, round the table.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param from - The source square or seat index.
+ * @param by - The direction or distance to step between seats.
+ * @returns The player a swipe or an arrow shows next: `by` seats on, round the table.
+ * @example
+ * ```ts
+ * import { startParty, stepView } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(stepView(game,0,1));
+ * ```
+ */
 export declare function stepView(game: PartyGame, from: number, by: number): number;