@johnmorrisdotca/kumimoji 1.2.2 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/CHANGELOG.md +21 -1
  2. package/README.md +80 -39
  3. package/dist/check.d.ts +26 -1
  4. package/dist/check.js +26 -1
  5. package/dist/computer.types.d.ts +24 -2
  6. package/dist/computerPlay.d.ts +45 -2
  7. package/dist/computerPlay.js +45 -2
  8. package/dist/computerTurn.d.ts +42 -3
  9. package/dist/computerTurn.js +42 -3
  10. package/dist/daily.d.ts +22 -2
  11. package/dist/daily.js +22 -2
  12. package/dist/element-define.d.ts +1 -1
  13. package/dist/element-define.js +3 -13
  14. package/dist/element.d.ts +85 -4
  15. package/dist/element.js +176 -45
  16. package/dist/embed-day.d.ts +4 -0
  17. package/dist/embed-day.js +23 -0
  18. package/dist/export.d.ts +123 -6
  19. package/dist/export.js +91 -4
  20. package/dist/generate.d.ts +14 -0
  21. package/dist/generate.js +14 -0
  22. package/dist/grid.d.ts +181 -10
  23. package/dist/grid.js +122 -7
  24. package/dist/help.d.ts +36 -3
  25. package/dist/help.js +36 -3
  26. package/dist/judge.d.ts +14 -0
  27. package/dist/judge.js +14 -0
  28. package/dist/kana.d.ts +23 -1
  29. package/dist/kana.js +23 -1
  30. package/dist/kumimoji.types.d.ts +70 -5
  31. package/dist/party.d.ts +268 -14
  32. package/dist/party.js +268 -14
  33. package/dist/party.types.d.ts +50 -2
  34. package/dist/partyKept.d.ts +74 -4
  35. package/dist/partyKept.js +74 -4
  36. package/dist/partySeats.d.ts +92 -6
  37. package/dist/partySeats.js +72 -4
  38. package/dist/partyTurns.d.ts +171 -5
  39. package/dist/partyTurns.js +171 -5
  40. package/dist/placement.d.ts +50 -2
  41. package/dist/placement.js +30 -0
  42. package/dist/play.d.ts +247 -15
  43. package/dist/play.js +237 -15
  44. package/dist/random.d.ts +34 -3
  45. package/dist/random.js +23 -2
  46. package/dist/react.d.ts +42 -4
  47. package/dist/react.js +22 -5
  48. package/dist/showcase.d.ts +83 -7
  49. package/dist/showcase.js +49 -4
  50. package/dist/strings.d.ts +54 -5
  51. package/dist/strings.js +34 -3
  52. package/dist/tableView.d.ts +151 -8
  53. package/dist/tableView.js +129 -6
  54. package/dist/tileFace.d.ts +59 -5
  55. package/dist/tileFace.js +48 -4
  56. package/dist/tileFamily.d.ts +9 -0
  57. package/dist/tileFamily.js +9 -0
  58. package/dist/tileWords.d.ts +93 -6
  59. package/dist/tileWords.js +83 -6
  60. package/dist/tileWordsModule.d.ts +11 -1
  61. package/dist/tileWordsModule.js +11 -1
  62. package/dist/tiles.constants.d.ts +99 -5
  63. package/dist/tiles.constants.js +99 -5
  64. package/dist/turn.d.ts +82 -4
  65. package/dist/turn.js +82 -4
  66. package/dist/ui/board.d.ts +60 -5
  67. package/dist/ui/board.js +28 -2
  68. package/dist/ui/mount.d.ts +41 -2
  69. package/dist/ui/mount.js +38 -1
  70. package/dist/ui/style.d.ts +6 -1
  71. package/dist/ui/style.js +6 -0
  72. package/dist/version.d.ts +9 -2
  73. package/dist/version.js +9 -2
  74. package/dist/wilds.d.ts +22 -1
  75. package/dist/wilds.js +22 -1
  76. package/package.json +64 -56
@@ -24,17 +24,90 @@ import type { PartyGame, PartySeat } from "./party.types.ts";
24
24
  * standing (`lastStanding`), and wins by laying a tile on a sound grid, as
25
25
  * when everybody else resigns — unless somebody joins first.
26
26
  */
27
- /** Why nobody can join now, or null when a hand can be dealt. */
27
+ /** Why nobody can join now, or null when a hand can be dealt.
28
+ *
29
+ * @example
30
+ * ```ts
31
+ * import type { JoinRefusal } from "@johnmorrisdotca/kumimoji";
32
+ *
33
+ * const value: JoinRefusal = "full";
34
+ * console.log(value);
35
+ * ```
36
+ */
28
37
  export type JoinRefusal = "over" | "full" | "lastRound" | "bag";
29
- /** Why nobody can join the table now, or null when a hand can be dealt. */
38
+ /** Why nobody can join the table now, or null when a hand can be dealt.
39
+ *
40
+ * @param game - The current immutable shared-bag party game.
41
+ * @returns Why nobody can join the table now, or null when a hand can be dealt.
42
+ * @example
43
+ * ```ts
44
+ * import { joinRefused, startParty } from "@johnmorrisdotca/kumimoji";
45
+ *
46
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
47
+ * const bag = "catdogsun";
48
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
49
+ * console.log(joinRefused(game));
50
+ * ```
51
+ */
30
52
  export declare function joinRefused(game: PartyGame): JoinRefusal | null;
31
- /** A player, or a computer, sat down after the last seat with the next hand out of the bag. */
53
+ /** A player, or a computer, sat down after the last seat with the next hand out of the bag.
54
+ *
55
+ * @param game - The current immutable shared-bag party game.
56
+ * @param seat - The local name and computer flag for the joining player.
57
+ * @returns A player, or a computer, sat down after the last seat with the next hand out of the bag.
58
+ * @example
59
+ * ```ts
60
+ * import { joinParty, startParty } from "@johnmorrisdotca/kumimoji";
61
+ *
62
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
63
+ * const bag = "catdogsun";
64
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
65
+ * console.log(joinParty(game,{name:"Seat 3"}).players.length);
66
+ * ```
67
+ */
32
68
  export declare function joinParty(game: PartyGame, seat: PartySeat): PartyGame;
33
- /** Why this player cannot leave now, or null when they can. */
69
+ /** Why this player cannot leave now, or null when they can.
70
+ *
71
+ * @example
72
+ * ```ts
73
+ * import type { LeaveRefusal } from "@johnmorrisdotca/kumimoji";
74
+ *
75
+ * const value: LeaveRefusal = "lastPerson";
76
+ * console.log(value);
77
+ * ```
78
+ */
34
79
  export type LeaveRefusal = "over" | "out" | "lastPerson";
35
- /** Why the player at seat `at` cannot leave now, or null when they can. */
80
+ /** Why the player at seat `at` cannot leave now, or null when they can.
81
+ *
82
+ * @param game - The current immutable shared-bag party game.
83
+ * @param at - The word offset, seat index or date specified by this signature.
84
+ * @returns Why the player at seat `at` cannot leave now, or null when they can.
85
+ * @example
86
+ * ```ts
87
+ * import { leaveRefused, startParty } from "@johnmorrisdotca/kumimoji";
88
+ *
89
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
90
+ * const bag = "catdogsun";
91
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
92
+ * console.log(leaveRefused(game,0));
93
+ * ```
94
+ */
36
95
  export declare function leaveRefused(game: PartyGame, at: number): LeaveRefusal | null;
37
- /** How many tiles a player would put back in the bag by leaving: their hand and their table. */
96
+ /** How many tiles a player would put back in the bag by leaving: their hand and their table.
97
+ *
98
+ * @param game - The current immutable shared-bag party game.
99
+ * @param at - The word offset, seat index or date specified by this signature.
100
+ * @returns How many tiles a player would put back in the bag by leaving: their hand and their table.
101
+ * @example
102
+ * ```ts
103
+ * import { startParty, tilesHeldBy } from "@johnmorrisdotca/kumimoji";
104
+ *
105
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
106
+ * const bag = "catdogsun";
107
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
108
+ * console.log(tilesHeldBy(game,0));
109
+ * ```
110
+ */
38
111
  export declare function tilesHeldBy(game: PartyGame, at: number): number;
39
112
  /**
40
113
  * A PLAYER LEAVES. Their tiles go back into the bag and the bag is shuffled
@@ -51,5 +124,18 @@ export declare function tilesHeldBy(game: PartyGame, at: number): number;
51
124
  * round to the next still to have their last turn; a last round with nobody
52
125
  * left to play ends. With nobody still in — everybody left has resigned —
53
126
  * the game ends tied between them.
127
+ *
128
+ * @param game - The current immutable shared-bag party game.
129
+ * @param at - The word offset, seat index or date specified by this signature.
130
+ * @returns A PLAYER LEAVES. Their tiles go back into the bag and the bag is shuffled — with the game's own seed and how far it has gone, so the same game left the same way deals the same tiles after a reload. A wild goes back blank.
131
+ * @example
132
+ * ```ts
133
+ * import { leaveParty, startParty } from "@johnmorrisdotca/kumimoji";
134
+ *
135
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
136
+ * const bag = "catdogsun";
137
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
138
+ * console.log(leaveParty(game,0).players.length);
139
+ * ```
54
140
  */
55
141
  export declare function leaveParty(game: PartyGame, at: number): PartyGame;
@@ -2,7 +2,20 @@ import { seededRandom, shuffled } from "./random.js";
2
2
  import { computerName, isComputer, nextIn, partyTilesLeft, stillIn, tableTally, tidyName } from "./party.js";
3
3
  import { tileFace } from "./tileFace.js";
4
4
  import { KUMIMOJI_PARTY } from "./tiles.constants.js";
5
- /** Why nobody can join the table now, or null when a hand can be dealt. */
5
+ /** Why nobody can join the table now, or null when a hand can be dealt.
6
+ *
7
+ * @param game - The current immutable shared-bag party game.
8
+ * @returns Why nobody can join the table now, or null when a hand can be dealt.
9
+ * @example
10
+ * ```ts
11
+ * import { joinRefused, startParty } from "@johnmorrisdotca/kumimoji";
12
+ *
13
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
14
+ * const bag = "catdogsun";
15
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
16
+ * console.log(joinRefused(game));
17
+ * ```
18
+ */
6
19
  export function joinRefused(game) {
7
20
  if (game.ending !== null)
8
21
  return "over";
@@ -14,7 +27,21 @@ export function joinRefused(game) {
14
27
  return "bag";
15
28
  return null;
16
29
  }
17
- /** A player, or a computer, sat down after the last seat with the next hand out of the bag. */
30
+ /** A player, or a computer, sat down after the last seat with the next hand out of the bag.
31
+ *
32
+ * @param game - The current immutable shared-bag party game.
33
+ * @param seat - The local name and computer flag for the joining player.
34
+ * @returns A player, or a computer, sat down after the last seat with the next hand out of the bag.
35
+ * @example
36
+ * ```ts
37
+ * import { joinParty, startParty } from "@johnmorrisdotca/kumimoji";
38
+ *
39
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
40
+ * const bag = "catdogsun";
41
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
42
+ * console.log(joinParty(game,{name:"Seat 3"}).players.length);
43
+ * ```
44
+ */
18
45
  export function joinParty(game, seat) {
19
46
  if (joinRefused(game) !== null)
20
47
  return game;
@@ -33,7 +60,21 @@ function freePlayerName(players) {
33
60
  if (!taken.has(`Player ${number}`))
34
61
  return `Player ${number}`;
35
62
  }
36
- /** Why the player at seat `at` cannot leave now, or null when they can. */
63
+ /** Why the player at seat `at` cannot leave now, or null when they can.
64
+ *
65
+ * @param game - The current immutable shared-bag party game.
66
+ * @param at - The word offset, seat index or date specified by this signature.
67
+ * @returns Why the player at seat `at` cannot leave now, or null when they can.
68
+ * @example
69
+ * ```ts
70
+ * import { leaveRefused, startParty } from "@johnmorrisdotca/kumimoji";
71
+ *
72
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
73
+ * const bag = "catdogsun";
74
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
75
+ * console.log(leaveRefused(game,0));
76
+ * ```
77
+ */
37
78
  export function leaveRefused(game, at) {
38
79
  if (game.ending !== null || game.players[at] === undefined)
39
80
  return "over";
@@ -43,7 +84,21 @@ export function leaveRefused(game, at) {
43
84
  return "lastPerson";
44
85
  return null;
45
86
  }
46
- /** How many tiles a player would put back in the bag by leaving: their hand and their table. */
87
+ /** How many tiles a player would put back in the bag by leaving: their hand and their table.
88
+ *
89
+ * @param game - The current immutable shared-bag party game.
90
+ * @param at - The word offset, seat index or date specified by this signature.
91
+ * @returns How many tiles a player would put back in the bag by leaving: their hand and their table.
92
+ * @example
93
+ * ```ts
94
+ * import { startParty, tilesHeldBy } from "@johnmorrisdotca/kumimoji";
95
+ *
96
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
97
+ * const bag = "catdogsun";
98
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
99
+ * console.log(tilesHeldBy(game,0));
100
+ * ```
101
+ */
47
102
  export function tilesHeldBy(game, at) {
48
103
  const player = game.players[at];
49
104
  return player === undefined ? 0 : player.hand.length + player.tiles.size;
@@ -63,6 +118,19 @@ export function tilesHeldBy(game, at) {
63
118
  * round to the next still to have their last turn; a last round with nobody
64
119
  * left to play ends. With nobody still in — everybody left has resigned —
65
120
  * the game ends tied between them.
121
+ *
122
+ * @param game - The current immutable shared-bag party game.
123
+ * @param at - The word offset, seat index or date specified by this signature.
124
+ * @returns A PLAYER LEAVES. Their tiles go back into the bag and the bag is shuffled — with the game's own seed and how far it has gone, so the same game left the same way deals the same tiles after a reload. A wild goes back blank.
125
+ * @example
126
+ * ```ts
127
+ * import { leaveParty, startParty } from "@johnmorrisdotca/kumimoji";
128
+ *
129
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
130
+ * const bag = "catdogsun";
131
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
132
+ * console.log(leaveParty(game,0).players.length);
133
+ * ```
66
134
  */
67
135
  export function leaveParty(game, at) {
68
136
  if (leaveRefused(game, at) !== null)
@@ -7,17 +7,72 @@ import type { TileWords } from "./tileWords.ts";
7
7
  * solo game's (`play.ts`), and the deal and the draw are `party.ts`'s. Pure:
8
8
  * each returns a new game, or the one it was given where the move is refused.
9
9
  */
10
- /** Whether the game is over. */
10
+ /** Whether the game is over.
11
+ *
12
+ * @param game - The current immutable shared-bag party game.
13
+ * @returns Whether the game is over.
14
+ * @example
15
+ * ```ts
16
+ * import { isOver, startParty } from "@johnmorrisdotca/kumimoji";
17
+ *
18
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
19
+ * const bag = "catdogsun";
20
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
21
+ * console.log(isOver(game));
22
+ * ```
23
+ */
11
24
  export declare function isOver(game: PartyGame): boolean;
12
25
  /**
13
26
  * Whether the player whose turn it is would go out with Done: their hand
14
27
  * used, their grid sound, and too few tiles in the bag for everybody still in
15
28
  * to draw.
29
+ *
30
+ * @param game - The current immutable shared-bag party game.
31
+ * @param verdict - The native word and connectivity verdict for this grid.
32
+ * @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.
33
+ * @example
34
+ * ```ts
35
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
36
+ * import { goesOut, judgeWithWords, startParty } from "@johnmorrisdotca/kumimoji";
37
+ *
38
+ * const words = await loadTileWordsFromModule("english");
39
+ * const verdict = judgeWithWords(new Map([["0,0","c"],["0,1","a"],["0,2","t"]]),words);
40
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
41
+ * const bag = "catdogsun";
42
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
43
+ * console.log(goesOut(game,verdict));
44
+ * ```
16
45
  */
17
46
  export declare function goesOut(game: PartyGame, verdict: GridVerdict): boolean;
18
- /** Whether the player whose turn it is has laid a tile on their table this turn: more tiles there than when it began. */
47
+ /** Whether the player whose turn it is has laid a tile on their table this turn: more tiles there than when it began.
48
+ *
49
+ * @param game - The current immutable shared-bag party game.
50
+ * @returns Whether the player whose turn it is has laid a tile on their table this turn: more tiles there than when it began.
51
+ * @example
52
+ * ```ts
53
+ * import { laidThisTurn, startParty } from "@johnmorrisdotca/kumimoji";
54
+ *
55
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
56
+ * const bag = "catdogsun";
57
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
58
+ * console.log(laidThisTurn(game));
59
+ * ```
60
+ */
19
61
  export declare function laidThisTurn(game: PartyGame): boolean;
20
- /** Whether the player whose turn it is is the only one still in: everybody else has resigned. */
62
+ /** Whether the player whose turn it is is the only one still in: everybody else has resigned.
63
+ *
64
+ * @param game - The current immutable shared-bag party game.
65
+ * @returns Whether the player whose turn it is is the only one still in: everybody else has resigned.
66
+ * @example
67
+ * ```ts
68
+ * import { lastStanding, startParty } from "@johnmorrisdotca/kumimoji";
69
+ *
70
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
71
+ * const bag = "catdogsun";
72
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
73
+ * console.log(lastStanding(game));
74
+ * ```
75
+ */
21
76
  export declare function lastStanding(game: PartyGame): boolean;
22
77
  /**
23
78
  * A HAND THAT SPELLS NOTHING MUST BE TRADED. John, 2026-09-28: "If no words
@@ -26,14 +81,59 @@ export declare function lastStanding(game: PartyGame): boolean;
26
81
  * spell no word, has laid nothing on (or lifted nothing from) their table this
27
82
  * turn, and has not traded — unless the bag cannot give three, when there is
28
83
  * nothing to trade for. `handSpells` answers for a hand (`handCanSpell`).
84
+ *
85
+ * @param game - The current immutable shared-bag party game.
86
+ * @param handSpells - Whether a hand can form any accepted word.
87
+ * @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`).
88
+ * @example
89
+ * ```ts
90
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
91
+ * import { handCanSpell, mustTradeFirst, startParty } from "@johnmorrisdotca/kumimoji";
92
+ *
93
+ * const words = await loadTileWordsFromModule("english");
94
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
95
+ * const bag = "catdogsun";
96
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
97
+ * console.log(mustTradeFirst(game,hand=>handCanSpell(hand,words)));
98
+ * ```
29
99
  */
30
100
  export declare function mustTradeFirst(game: PartyGame, handSpells: (hand: readonly string[]) => boolean): boolean;
31
- /** 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. */
101
+ /** 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.
102
+ *
103
+ * @param hand - The hand size or tile codes, as declared by the function signature.
104
+ * @param words - The loaded native language word list and tile mappings.
105
+ * @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.
106
+ * @example
107
+ * ```ts
108
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
109
+ * import { handCanSpell } from "@johnmorrisdotca/kumimoji";
110
+ *
111
+ * const words = await loadTileWordsFromModule("english");
112
+ * console.log(handCanSpell(["c","a","t"],words));
113
+ * ```
114
+ */
32
115
  export declare function handCanSpell(hand: readonly string[], words: TileWords): boolean;
33
116
  /**
34
117
  * Why Done cannot be pressed now, or null when it can: a hand to trade first,
35
118
  * or, for the last one standing, no tile laid on a sound grid yet (a hand
36
119
  * already used on a sound grid has nothing left to lay, and wins as it is).
120
+ *
121
+ * @param game - The current immutable shared-bag party game.
122
+ * @param verdict - The native word and connectivity verdict for this grid.
123
+ * @param handSpells - Whether a hand can form any accepted word.
124
+ * @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).
125
+ * @example
126
+ * ```ts
127
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
128
+ * import { doneRefused, handCanSpell, judgeWithWords, seatPlay, startParty } from "@johnmorrisdotca/kumimoji";
129
+ *
130
+ * const words = await loadTileWordsFromModule("english");
131
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
132
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
133
+ * const bag = "catdogsun";
134
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
135
+ * console.log(doneRefused(game,judgeWithWords(seatPlay(game).tiles,words),hand=>handCanSpell(hand,words)));
136
+ * ```
37
137
  */
38
138
  export declare function doneRefused(game: PartyGame, verdict: GridVerdict, handSpells: (hand: readonly string[]) => boolean): "trade" | "standing" | null;
39
139
  /**
@@ -46,6 +146,23 @@ export declare function doneRefused(game: PartyGame, verdict: GridVerdict, handS
46
146
  * The last one standing, everybody else resigned, wins by laying a tile on a
47
147
  * sound grid and pressing Done. `verdict` is the grid of the player whose turn
48
148
  * it is. Refused, the game given back as it was, while `doneRefused` says so.
149
+ *
150
+ * @param game - The current immutable shared-bag party game.
151
+ * @param verdict - The native word and connectivity verdict for this grid.
152
+ * @param handSpells - Whether a hand can form any accepted word.
153
+ * @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.
154
+ * @example
155
+ * ```ts
156
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
157
+ * import { endTurn, handCanSpell, judgeWithWords, seatPlay, startParty } from "@johnmorrisdotca/kumimoji";
158
+ *
159
+ * const words = await loadTileWordsFromModule("english");
160
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
161
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
162
+ * const bag = "catdogsun";
163
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
164
+ * console.log(endTurn(game,judgeWithWords(seatPlay(game).tiles,words),hand=>handCanSpell(hand,words)).turn);
165
+ * ```
49
166
  */
50
167
  export declare function endTurn(game: PartyGame, verdict: GridVerdict, handSpells: (hand: readonly string[]) => boolean): PartyGame;
51
168
  /**
@@ -53,6 +170,18 @@ export declare function endTurn(game: PartyGame, verdict: GridVerdict, handSpell
53
170
  * give a trade, so nothing more can be got from it. John, 2026-09-28:
54
171
  * "Perhaps we offer a resign button only when there are no remaining tiles
55
172
  * they can get from the bag."
173
+ *
174
+ * @param game - The current immutable shared-bag party game.
175
+ * @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."
176
+ * @example
177
+ * ```ts
178
+ * import { mayResign, startParty } from "@johnmorrisdotca/kumimoji";
179
+ *
180
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
181
+ * const bag = "catdogsun";
182
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
183
+ * console.log(mayResign(game));
184
+ * ```
56
185
  */
57
186
  export declare function mayResign(game: PartyGame): boolean;
58
187
  /**
@@ -63,13 +192,50 @@ export declare function mayResign(game: PartyGame): boolean;
63
192
  * resigned too — it ends tied between everybody who resigned since a player
64
193
  * still in last pressed Done. John: "if you resign, as the turns pass, if
65
194
  * someone else can't go and has to resign then they are tied."
195
+ *
196
+ * @param game - The current immutable shared-bag party game.
197
+ * @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."
198
+ * @example
199
+ * ```ts
200
+ * import { resign, startParty } from "@johnmorrisdotca/kumimoji";
201
+ *
202
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
203
+ * const bag = "catdogsun";
204
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
205
+ * console.log(resign(game));
206
+ * ```
66
207
  */
67
208
  export declare function resign(game: PartyGame): PartyGame;
68
209
  /**
69
210
  * The winners of a finished game, by place: everybody who went out; the last
70
211
  * one standing; or, tied, the final run of resignations. Empty while it is
71
212
  * played.
213
+ *
214
+ * @param game - The current immutable shared-bag party game.
215
+ * @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.
216
+ * @example
217
+ * ```ts
218
+ * import { startParty, winnersOf } from "@johnmorrisdotca/kumimoji";
219
+ *
220
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
221
+ * const bag = "catdogsun";
222
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
223
+ * console.log(winnersOf(game));
224
+ * ```
72
225
  */
73
226
  export declare function winnersOf(game: PartyGame): readonly number[];
74
- /** Whether the turn now being played is a player's last. */
227
+ /** Whether the turn now being played is a player's last.
228
+ *
229
+ * @param game - The current immutable shared-bag party game.
230
+ * @returns Whether the turn now being played is a player's last.
231
+ * @example
232
+ * ```ts
233
+ * import { isLastTurn, startParty } from "@johnmorrisdotca/kumimoji";
234
+ *
235
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
236
+ * const bag = "catdogsun";
237
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
238
+ * console.log(isLastTurn(game));
239
+ * ```
240
+ */
75
241
  export declare function isLastTurn(game: PartyGame): boolean;