@johnmorrisdotca/kumimoji 1.2.1 → 1.3.0

package/dist/partyTurns.js

@@ -8,7 +8,20 @@ import { KUMIMOJI_TRADE } from "./tiles.constants.js";
  * solo game's (`play.ts`), and the deal and the draw are `party.ts`'s. Pure:
  * each returns a new game, or the one it was given where the move is refused.
  */
-/** Whether the game is over. */
+/** Whether the game is over.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns Whether the game is over.
+ * @example
+ * ```ts
+ * import { isOver, 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(isOver(game));
+ * ```
+ */
 export function isOver(game) {
     return game.ending !== null;
 }
@@ -16,15 +29,57 @@ export function isOver(game) {
  * Whether the player whose turn it is would go out with Done: their hand
  * used, their grid sound, and too few tiles in the bag for everybody still in
  * to draw.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param verdict - The native word and connectivity verdict for this grid.
+ * @returns Whether the player whose turn it is would go out with Done: their hand used, their grid sound, and too few tiles in the bag for everybody still in to draw.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { goesOut, judgeWithWords, 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(goesOut(game,verdict));
+ * ```
  */
 export function goesOut(game, verdict) {
     return !isOver(game) && game.players[game.turn].hand.length === 0 && verdict.sound && partyTilesLeft(game) < stillIn(game).length;
 }
-/** Whether the player whose turn it is has laid a tile on their table this turn: more tiles there than when it began. */
+/** Whether the player whose turn it is has laid a tile on their table this turn: more tiles there than when it began.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns Whether the player whose turn it is has laid a tile on their table this turn: more tiles there than when it began.
+ * @example
+ * ```ts
+ * import { laidThisTurn, 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(laidThisTurn(game));
+ * ```
+ */
 export function laidThisTurn(game) {
     return game.players[game.turn].tiles.size > [...game.startTable].length;
 }
-/** Whether the player whose turn it is is the only one still in: everybody else has resigned. */
+/** Whether the player whose turn it is is the only one still in: everybody else has resigned.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns Whether the player whose turn it is is the only one still in: everybody else has resigned.
+ * @example
+ * ```ts
+ * import { lastStanding, 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(lastStanding(game));
+ * ```
+ */
 export function lastStanding(game) {
     return !isOver(game) && game.lastTurns === null && stillIn(game).length === 1;
 }
@@ -35,6 +90,21 @@ export function lastStanding(game) {
  * spell no word, has laid nothing on (or lifted nothing from) their table this
  * turn, and has not traded — unless the bag cannot give three, when there is
  * nothing to trade for. `handSpells` answers for a hand (`handCanSpell`).
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param handSpells - Whether a hand can form any accepted word.
+ * @returns A HAND THAT SPELLS NOTHING MUST BE TRADED. John, 2026-09-28: "If no words can be formed which is possible, they must dump a tile to get 3 more. Easy rule." So Done waits while the player whose turn it is holds tiles that spell no word, has laid nothing on (or lifted nothing from) their table this turn, and has not traded — unless the bag cannot give three, when there is nothing to trade for. `handSpells` answers for a hand (`handCanSpell`).
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { handCanSpell, mustTradeFirst, 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(mustTradeFirst(game,hand=>handCanSpell(hand,words)));
+ * ```
  */
 export function mustTradeFirst(game, handSpells) {
     if (isOver(game) || game.traded)
@@ -44,7 +114,20 @@ export function mustTradeFirst(game, handSpells) {
         return false;
     return !handSpells(play.hand);
 }
-/** Whether a hand can spell a word from the list: any word of two tiles or more, a wild counting as able to be anything. */
+/** Whether a hand can spell a word from the list: any word of two tiles or more, a wild counting as able to be anything.
+ *
+ * @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 Whether a hand can spell a word from the list: any word of two tiles or more, a wild counting as able to be anything.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { handCanSpell } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * console.log(handCanSpell(["c","a","t"],words));
+ * ```
+ */
 export function handCanSpell(hand, words) {
     return hand.some(words.isWild) || wordsInHand(hand, words).length > 0;
 }
@@ -52,6 +135,23 @@ export function handCanSpell(hand, words) {
  * Why Done cannot be pressed now, or null when it can: a hand to trade first,
  * or, for the last one standing, no tile laid on a sound grid yet (a hand
  * already used on a sound grid has nothing left to lay, and wins as it is).
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param verdict - The native word and connectivity verdict for this grid.
+ * @param handSpells - Whether a hand can form any accepted word.
+ * @returns Why Done cannot be pressed now, or null when it can: a hand to trade first, or, for the last one standing, no tile laid on a sound grid yet (a hand already used on a sound grid has nothing left to lay, and wins as it is).
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { doneRefused, handCanSpell, judgeWithWords, seatPlay, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * 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(doneRefused(game,judgeWithWords(seatPlay(game).tiles,words),hand=>handCanSpell(hand,words)));
+ * ```
  */
 export function doneRefused(game, verdict, handSpells) {
     if (mustTradeFirst(game, handSpells))
@@ -75,6 +175,23 @@ function passTo(game, turn, rest) {
  * The last one standing, everybody else resigned, wins by laying a tile on a
  * sound grid and pressing Done. `verdict` is the grid of the player whose turn
  * it is. Refused, the game given back as it was, while `doneRefused` says so.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param verdict - The native word and connectivity verdict for this grid.
+ * @param handSpells - Whether a hand can form any accepted word.
+ * @returns DONE: the end of a turn, and the device passed on. Before anybody is out, to the next player still in. A player who goes out with it starts the last round: everybody else still in, in order from the next, has one last turn, and any of them who goes out on it shares the win (John, 2026-09-28: "Sharing the win is correct"). After the last of those, the game is over.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { endTurn, handCanSpell, judgeWithWords, seatPlay, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * 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(endTurn(game,judgeWithWords(seatPlay(game).tiles,words),hand=>handCanSpell(hand,words)).turn);
+ * ```
  */
 export function endTurn(game, verdict, handSpells) {
     if (isOver(game) || doneRefused(game, verdict, handSpells) !== null)
@@ -108,6 +225,18 @@ function nextLastTurn(game, out, rest = {}) {
  * give a trade, so nothing more can be got from it. John, 2026-09-28:
  * "Perhaps we offer a resign button only when there are no remaining tiles
  * they can get from the bag."
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns Whether the player whose turn it is may resign: only once the bag cannot give a trade, so nothing more can be got from it. John, 2026-09-28: "Perhaps we offer a resign button only when there are no remaining tiles they can get from the bag."
+ * @example
+ * ```ts
+ * import { mayResign, 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(mayResign(game));
+ * ```
  */
 export function mayResign(game) {
     return !isOver(game) && partyTilesLeft(game) < KUMIMOJI_TRADE.take;
@@ -120,6 +249,18 @@ export function mayResign(game) {
  * resigned too — it ends tied between everybody who resigned since a player
  * still in last pressed Done. John: "if you resign, as the turns pass, if
  * someone else can't go and has to resign then they are tied."
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns RESIGN: the player whose turn it is is out of the game, their table kept for the finish, and their turn passed over from then on. In the last round it is their last turn ended without going out. Otherwise the game goes on with whoever is still in; and when nobody is — the last one standing resigned too — it ends tied between everybody who resigned since a player still in last pressed Done. John: "if you resign, as the turns pass, if someone else can't go and has to resign then they are tied."
+ * @example
+ * ```ts
+ * import { resign, 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(resign(game));
+ * ```
  */
 export function resign(game) {
     if (!mayResign(game))
@@ -137,6 +278,18 @@ export function resign(game) {
  * The winners of a finished game, by place: everybody who went out; the last
  * one standing; or, tied, the final run of resignations. Empty while it is
  * played.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns The winners of a finished game, by place: everybody who went out; the last one standing; or, tied, the final run of resignations. Empty while it is played.
+ * @example
+ * ```ts
+ * import { startParty, winnersOf } 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(winnersOf(game));
+ * ```
  */
 export function winnersOf(game) {
     if (game.ending === "out")
@@ -147,7 +300,20 @@ export function winnersOf(game) {
         return game.resignRun;
     return [];
 }
-/** Whether the turn now being played is a player's last. */
+/** Whether the turn now being played is a player's last.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @returns Whether the turn now being played is a player's last.
+ * @example
+ * ```ts
+ * import { isLastTurn, 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(isLastTurn(game));
+ * ```
+ */
 export function isLastTurn(game) {
     return !isOver(game) && game.lastTurns !== null;
 }

package/dist/placement.d.ts

@@ -1,9 +1,27 @@
-/** A square by its row and column. */
+/** A square by its row and column.
+ *
+ * @example
+ * ```ts
+ * import type { Square } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: Square = {row:0,col:0};
+ * console.log(value);
+ * ```
+ */
 export type Square = {
     row: number;
     col: number;
 };
-/** A word's place: its first square, and the squares it lays a new tile on, in the word's order. */
+/** A word's place: its first square, and the squares it lays a new tile on, in the word's order.
+ *
+ * @example
+ * ```ts
+ * import type { CrossingFit } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: CrossingFit = {first:{row:0,col:0},fresh:[{row:0,col:1},{row:0,col:2}]};
+ * console.log(value);
+ * ```
+ */
 export type CrossingFit = {
     first: Square;
     fresh: Square[];
@@ -15,6 +33,21 @@ export type CrossingFit = {
  * neighbour at its side, or no new tile at all — and, given `diagonalWord`
  * (a game with Diagonals), a new tile standing in a diagonal run of three or
  * more that `diagonalWord` does not take (`diagonalsRead`).
+ *
+ * @param letterAt - The tile at a coordinate, or an empty string for no tile.
+ * @param inside - Whether a coordinate is within the caller’s working grid.
+ * @param word - The encoded word to lay or spell.
+ * @param anchor - The existing tile that the word crosses.
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @param across - Whether to lay or type horizontally rather than vertically.
+ * @param diagonalWord - Optional diagonal-word predicate; null disables diagonal checking.
+ * @returns Where `word` stands with its letter `at` on the tile at `anchor`, running across or down, or null where it cannot: a square outside what may be used, a tile at either end, a different letter in its way, a new tile with a neighbour at its side, or no new tile at all — and, given `diagonalWord` (a game with Diagonals), a new tile standing in a diagonal run of three or more that `diagonalWord` does not take (`diagonalsRead`).
+ * @example
+ * ```ts
+ * import { crossingFit } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(crossingFit((r,c)=>r===0&&c===0?"c":"",()=>true,"cat",{row:0,col:0},0,true));
+ * ```
  */
 export declare function crossingFit(letterAt: (row: number, col: number) => string, inside: (row: number, col: number) => boolean, word: string, anchor: Square, at: number, across: boolean, diagonalWord?: ((run: string) => boolean) | null): CrossingFit | null;
 /**
@@ -23,5 +56,20 @@ export declare function crossingFit(letterAt: (row: number, col: number) => stri
  * its new squares. Only a run through a new tile can change, and two new
  * tiles of one word never share a diagonal (they share a row or a column), so
  * each is read on its own. A run of two, a corner touch, is never read.
+ *
+ * @param letterAt - The tile at a coordinate, or an empty string for no tile.
+ * @param inside - Whether a coordinate is within the caller’s working grid.
+ * @param word - The encoded word to lay or spell.
+ * @param fit - The first coordinate and fresh tile coordinates of the proposed laying.
+ * @param isWord - The predicate that accepts a readable word.
+ * @returns Whether every diagonal run a laying's new tiles would stand in is taken by `isWord`: each walked from its top end down, with the word's own letters on its new squares. Only a run through a new tile can change, and two new tiles of one word never share a diagonal (they share a row or a column), so each is read on its own. A run of two, a corner touch, is never read.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { diagonalsRead } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * console.log(diagonalsRead(()=>"",()=>true,"cat",{first:{row:0,col:0},fresh:[{row:0,col:0},{row:0,col:1},{row:0,col:2}]},word=>words.allowed.has(word)));
+ * ```
  */
 export declare function diagonalsRead(letterAt: (row: number, col: number) => string, inside: (row: number, col: number) => boolean, word: string, fit: CrossingFit, isWord: (run: string) => boolean): boolean;

package/dist/placement.js

@@ -28,6 +28,21 @@ import { DIAGONAL_RUN_LEAST } from "./grid.js";
  * neighbour at its side, or no new tile at all — and, given `diagonalWord`
  * (a game with Diagonals), a new tile standing in a diagonal run of three or
  * more that `diagonalWord` does not take (`diagonalsRead`).
+ *
+ * @param letterAt - The tile at a coordinate, or an empty string for no tile.
+ * @param inside - Whether a coordinate is within the caller’s working grid.
+ * @param word - The encoded word to lay or spell.
+ * @param anchor - The existing tile that the word crosses.
+ * @param at - The word offset, seat index or date specified by this signature.
+ * @param across - Whether to lay or type horizontally rather than vertically.
+ * @param diagonalWord - Optional diagonal-word predicate; null disables diagonal checking.
+ * @returns Where `word` stands with its letter `at` on the tile at `anchor`, running across or down, or null where it cannot: a square outside what may be used, a tile at either end, a different letter in its way, a new tile with a neighbour at its side, or no new tile at all — and, given `diagonalWord` (a game with Diagonals), a new tile standing in a diagonal run of three or more that `diagonalWord` does not take (`diagonalsRead`).
+ * @example
+ * ```ts
+ * import { crossingFit } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(crossingFit((r,c)=>r===0&&c===0?"c":"",()=>true,"cat",{row:0,col:0},0,true));
+ * ```
  */
 export function crossingFit(letterAt, inside, word, anchor, at, across, diagonalWord = null) {
     const dr = across ? 0 : 1;
@@ -67,6 +82,21 @@ export function crossingFit(letterAt, inside, word, anchor, at, across, diagonal
  * its new squares. Only a run through a new tile can change, and two new
  * tiles of one word never share a diagonal (they share a row or a column), so
  * each is read on its own. A run of two, a corner touch, is never read.
+ *
+ * @param letterAt - The tile at a coordinate, or an empty string for no tile.
+ * @param inside - Whether a coordinate is within the caller’s working grid.
+ * @param word - The encoded word to lay or spell.
+ * @param fit - The first coordinate and fresh tile coordinates of the proposed laying.
+ * @param isWord - The predicate that accepts a readable word.
+ * @returns Whether every diagonal run a laying's new tiles would stand in is taken by `isWord`: each walked from its top end down, with the word's own letters on its new squares. Only a run through a new tile can change, and two new tiles of one word never share a diagonal (they share a row or a column), so each is read on its own. A run of two, a corner touch, is never read.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { diagonalsRead } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * console.log(diagonalsRead(()=>"",()=>true,"cat",{first:{row:0,col:0},fresh:[{row:0,col:0},{row:0,col:1},{row:0,col:2}]},word=>words.allowed.has(word)));
+ * ```
  */
 export function diagonalsRead(letterAt, inside, word, fit, isWord) {
     const freshAt = new Map(fit.fresh.map((square) => [`${square.row},${square.col}`, word[(square.row - fit.first.row) + (square.col - fit.first.col)]]));