@johnmorrisdotca/kumimoji 1.2.2 → 1.3.0

package/dist/party.js

@@ -15,15 +15,48 @@ import { KUMIMOJI_PARTY, kumimojiTileCount } from "./tiles.constants.js";
  * 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 function partyTilesNeeded(players, hand) {
     return players * hand + players;
 }
-/** 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 function partyFits(players, hand, tiles) {
     return players < KUMIMOJI_PARTY.least || tiles >= partyTilesNeeded(players, hand);
 }
-/** 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 function partyPlayersAsked(value) {
     const count = Number(value);
     return Number.isInteger(count) && count >= KUMIMOJI_PARTY.least && count <= KUMIMOJI_PARTY.most ? count : 1;
@@ -35,6 +68,18 @@ const LENGTHS = ["short", "medium", "full"];
  * 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 function partyLength(players, hand, chosen, doubleSet) {
     // One player plays any length, and asks nothing of the size: the set-up screen asks this of every puzzle's.
@@ -49,6 +94,19 @@ export function partyLength(players, hand, chosen, doubleSet) {
  * 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 function startParty(settings, bag, seats) {
     const count = Math.min(Math.max(seats.length, KUMIMOJI_PARTY.least), KUMIMOJI_PARTY.most);
@@ -64,31 +122,106 @@ export function startParty(settings, bag, seats) {
     }
     return { settings, bag, returned: "", taken: count * hand, players, dealt: count, turn: 0, turns: 0, out: [], lastTurns: null, resigned: [], resignRun: [], ending: null, startTable: "", traded: false, passedBy: null };
 }
-/** 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 function computerName(players) {
     const taken = new Set(players.map((player) => player.name));
     for (let number = 1;; number += 1)
         if (!taken.has(`Computer ${number}`))
             return `Computer ${number}`;
 }
-/** 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 function isComputer(game, at) {
     return game.players[at]?.computer === true;
 }
-/** 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 function tableTally(tiles) {
     return [...tiles.values()].sort().join("");
 }
-/** 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 function tidyName(name) {
     return name.replace(/\s+/g, " ").trim().slice(0, KUMIMOJI_PARTY.nameMost);
 }
-/** 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 function nameOf(game, at) {
     const name = game.players[at]?.name ?? "";
     return name === "" ? `Player ${at + 1}` : name;
 }
-/** 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 function seatPlay(game) {
     const player = game.players[game.turn];
     return { bag: game.bag, returned: game.returned, taken: game.taken, tiles: player.tiles, hand: player.hand };
@@ -100,11 +233,37 @@ export function seatPlay(game) {
  * 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 function mayTradeThisTurn(game) {
     return game.ending === null && !game.traded && mayTrade(seatPlay(game));
 }
-/** 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 function withSeatPlay(game, play) {
     if (game.ending !== null)
         return game;
@@ -114,15 +273,55 @@ export function withSeatPlay(game, play) {
     const traded = game.traded || play.returned.length > game.returned.length;
     return { ...game, returned: play.returned, taken: play.taken, players, traded };
 }
-/** 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 function partyTilesLeft(game) {
     return tilesLeft(seatPlay(game));
 }
-/** 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 function stillIn(game) {
     return game.players.flatMap((_, at) => (game.resigned.includes(at) ? [] : [at]));
 }
-/** 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 function nextIn(game, from) {
     const count = game.players.length;
     for (let step = 1; step <= count; step += 1) {
@@ -136,6 +335,22 @@ export function nextIn(game, from) {
  * 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 function mayDrawAll(game, verdict) {
     return game.ending === null && game.lastTurns === null && game.players[game.turn].hand.length === 0 && verdict.sound && partyTilesLeft(game) >= stillIn(game).length;
@@ -144,6 +359,18 @@ export function mayDrawAll(game, verdict) {
  * 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 function drawAll(game) {
     const count = game.players.length;
@@ -161,11 +388,38 @@ export function drawAll(game) {
  * 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 function passViewStart(game) {
     return game.passedBy ?? game.turn;
 }
-/** 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 function stepView(game, from, by) {
     const count = game.players.length;
     return (((from + by) % count) + count) % count;

package/dist/party.types.d.ts

@@ -1,6 +1,16 @@
 import type { Tiles } from "./grid.ts";
 import type { KumimojiLanguage, KumimojiLength, KumimojiLevel } from "./kumimoji.types.ts";
-/** What a pass-and-play game was set up as: the address's own choices, which a kept game is matched to. */
+/** What a pass-and-play game was set up as: the address's own choices, which a kept game is matched to.
+ *
+ * @example
+ * ```ts
+ * import type { PartySettings } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const value: PartySettings = settings;
+ * console.log(value);
+ * ```
+ */
 export type PartySettings = {
     /** The hand each player is dealt: 7 Quick or 11 Classic (3 in the browser tests alone). */
     size: number;
@@ -20,6 +30,15 @@ export type PartySettings = {
  * their own table, and whether the seat is a computer's (`computerTurn.ts`),
  * whose turns play themselves in the browser. A computer's name is always
  * written out ("Computer 1"), never left for its number.
+ *
+ * @example
+ * ```ts
+ * import type { PartyPlayer } from "@johnmorrisdotca/kumimoji";
+ *
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * const value: PartyPlayer = {name:"Seat 1",hand:["c","a","t"],tiles:new Map()};
+ * console.log(value);
+ * ```
  */
 export type PartyPlayer = {
     name: string;
@@ -27,7 +46,16 @@ export type PartyPlayer = {
     tiles: Tiles;
     computer?: boolean;
 };
-/** A seat asked for before the deal or at a join: a name (empty for its number) and whether a computer plays it. */
+/** A seat asked for before the deal or at a join: a name (empty for its number) and whether a computer plays it.
+ *
+ * @example
+ * ```ts
+ * import type { PartySeat } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: PartySeat = {name:"Computer",computer:true};
+ * console.log(value);
+ * ```
+ */
 export type PartySeat = {
     name: string;
     computer?: boolean;
@@ -35,6 +63,18 @@ export type PartySeat = {
 /**
  * A PASS-AND-PLAY KUMIMOJI: one bag, read as a line the way the solo game
  * reads it (`TilePlay`), and a hand and a table for each player.
+ *
+ * @example
+ * ```ts
+ * import { startParty } from "@johnmorrisdotca/kumimoji";
+ * import type { PartyGame } 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"]);
+ * const value: PartyGame = game;
+ * console.log(value);
+ * ```
  */
 export type PartyGame = {
     settings: PartySettings;
@@ -82,5 +122,13 @@ export type PartyGame = {
  * had a last turn; the winners are everybody who went out. `standing`: every
  * other player resigned and the last one in laid a tile. `tied`: nobody was
  * left standing, and the players who resigned in that final run are tied.
+ *
+ * @example
+ * ```ts
+ * import type { PartyEnding } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: PartyEnding = "out";
+ * console.log(value);
+ * ```
  */
 export type PartyEnding = "out" | "standing" | "tied";

package/dist/partyKept.d.ts

@@ -1,7 +1,31 @@
 import type { PartyGame, PartySettings } from "./party.types.ts";
-/** A table of players as text to keep. `decodeParty` reads it back, and given the word list's `familyKey` checks every tile held against the bag. */
+/** A table of players as text to keep. `decodeParty` reads it back, and given the word list's `familyKey` checks every tile held against the bag.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns A table of players as text to keep. `decodeParty` reads it back, and given the word list's `familyKey` checks every tile held against the bag.
+ * @example
+ * ```ts
+ * import { encodeParty, 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(encodeParty(game));
+ * ```
+ */
 export declare function encodeParty(game: PartyGame): string;
-/** A game's settings as something outside this browser sent them — a table on several devices, a kept game — checked, or null. */
+/** A game's settings as something outside this browser sent them — a table on several devices, a kept game — checked, or null.
+ *
+ * @param value - The unknown setup value to interpret.
+ * @returns A game's settings as something outside this browser sent them — a table on several devices, a kept game — checked, or null.
+ * @example
+ * ```ts
+ * import { readSettings } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * console.log(readSettings(settings));
+ * ```
+ */
 export declare function readSettings(value: unknown): PartySettings | null;
 /**
  * A kept game read back, or null for anything that is not one. With
@@ -10,9 +34,55 @@ export declare function readSettings(value: unknown): PartySettings | null;
  * it and not given back, as the solo game checks a kept run
  * (`decodeTileProgress`). Without, its shape alone, which is enough to offer
  * it on the set-up screen.
+ *
+ * @param code - The encoded grid or progress text.
+ * @param familyKey - The function identifying physical tile families, or null for invalid codes.
+ * @returns A kept game read back, or null for anything that is not one. With `familyKey` (the loaded word list's), it is also checked against its own bag: every tile held by anybody — hand and table — must be one taken out of it and not given back, as the solo game checks a kept run (`decodeTileProgress`). Without, its shape alone, which is enough to offer it on the set-up screen.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { decodeParty, encodeParty, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * 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(decodeParty(encodeParty(game),words.familyKey)?.players.length);
+ * ```
  */
 export declare function decodeParty(code: string | null, familyKey?: (tile: string) => string | null): PartyGame | null;
-/** Whether what everybody holds is exactly what was taken from the bag, less what was given back. */
+/** Whether what everybody holds is exactly what was taken from the bag, less what was given back.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param familyKey - The function identifying physical tile families, or null for invalid codes.
+ * @returns Whether what everybody holds is exactly what was taken from the bag, less what was given back.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { holdsItsBag, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * 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(holdsItsBag(game,words.familyKey));
+ * ```
+ */
 export declare function holdsItsBag(game: PartyGame, familyKey: (tile: string) => string | null): boolean;
-/** Whether a kept game is the one an address asks for: the same settings, and dealt to as many players, whoever has joined or left since. */
+/** Whether a kept game is the one an address asks for: the same settings, and dealt to as many players, whoever has joined or left since.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param settings - The native party setup settings.
+ * @param players - The requested player count or current player rows.
+ * @returns Whether a kept game is the one an address asks for: the same settings, and dealt to as many players, whoever has joined or left since.
+ * @example
+ * ```ts
+ * import { isPartyFor, 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(isPartyFor(game,settings,2));
+ * ```
+ */
 export declare function isPartyFor(game: PartyGame, settings: PartySettings, players: number): boolean;

package/dist/partyKept.js

@@ -18,7 +18,20 @@ import { KUMIMOJI_PARTY, KUMIMOJI_HANDS } from "./tiles.constants.js";
  * nothing to check, and the names in it are the players' own business.
  */
 const VERSION = 1;
-/** A table of players as text to keep. `decodeParty` reads it back, and given the word list's `familyKey` checks every tile held against the bag. */
+/** A table of players as text to keep. `decodeParty` reads it back, and given the word list's `familyKey` checks every tile held against the bag.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns A table of players as text to keep. `decodeParty` reads it back, and given the word list's `familyKey` checks every tile held against the bag.
+ * @example
+ * ```ts
+ * import { encodeParty, 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(encodeParty(game));
+ * ```
+ */
 export function encodeParty(game) {
     const kept = {
         v: VERSION,
@@ -43,7 +56,18 @@ export function encodeParty(game) {
 }
 const isCount = (value, most) => Number.isInteger(value) && value >= 0 && value <= most;
 const isTiles = (value) => typeof value === "string" && /^[a-zA-Z*-]*$/.test(value);
-/** A game's settings as something outside this browser sent them — a table on several devices, a kept game — checked, or null. */
+/** A game's settings as something outside this browser sent them — a table on several devices, a kept game — checked, or null.
+ *
+ * @param value - The unknown setup value to interpret.
+ * @returns A game's settings as something outside this browser sent them — a table on several devices, a kept game — checked, or null.
+ * @example
+ * ```ts
+ * import { readSettings } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * console.log(readSettings(settings));
+ * ```
+ */
 export function readSettings(value) {
     if (typeof value !== "object" || value === null)
         return null;
@@ -73,6 +97,21 @@ export function readSettings(value) {
  * it and not given back, as the solo game checks a kept run
  * (`decodeTileProgress`). Without, its shape alone, which is enough to offer
  * it on the set-up screen.
+ *
+ * @param code - The encoded grid or progress text.
+ * @param familyKey - The function identifying physical tile families, or null for invalid codes.
+ * @returns A kept game read back, or null for anything that is not one. With `familyKey` (the loaded word list's), it is also checked against its own bag: every tile held by anybody — hand and table — must be one taken out of it and not given back, as the solo game checks a kept run (`decodeTileProgress`). Without, its shape alone, which is enough to offer it on the set-up screen.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { decodeParty, encodeParty, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * 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(decodeParty(encodeParty(game),words.familyKey)?.players.length);
+ * ```
  */
 export function decodeParty(code, familyKey) {
     if (code === null)
@@ -120,7 +159,23 @@ export function decodeParty(code, familyKey) {
         return null;
     return game;
 }
-/** Whether what everybody holds is exactly what was taken from the bag, less what was given back. */
+/** Whether what everybody holds is exactly what was taken from the bag, less what was given back.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param familyKey - The function identifying physical tile families, or null for invalid codes.
+ * @returns Whether what everybody holds is exactly what was taken from the bag, less what was given back.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { holdsItsBag, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * 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(holdsItsBag(game,words.familyKey));
+ * ```
+ */
 export function holdsItsBag(game, familyKey) {
     const taken = [...(game.bag + game.returned).slice(0, game.taken)].map(familyKey);
     const back = [...game.returned].map(familyKey);
@@ -135,7 +190,22 @@ export function holdsItsBag(game, familyKey) {
             tally.delete(tile);
     return sameLetters(tally, lettersOf(held));
 }
-/** Whether a kept game is the one an address asks for: the same settings, and dealt to as many players, whoever has joined or left since. */
+/** Whether a kept game is the one an address asks for: the same settings, and dealt to as many players, whoever has joined or left since.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param settings - The native party setup settings.
+ * @param players - The requested player count or current player rows.
+ * @returns Whether a kept game is the one an address asks for: the same settings, and dealt to as many players, whoever has joined or left since.
+ * @example
+ * ```ts
+ * import { isPartyFor, 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(isPartyFor(game,settings,2));
+ * ```
+ */
 export function isPartyFor(game, settings, players) {
     const a = game.settings;
     return (game.dealt === players &&