@johnmorrisdotca/kumimoji 1.0.1

package/dist/party.d.ts

@@ -0,0 +1,91 @@
+import type { GridVerdict, Tiles } from "./grid.ts";
+import type { KumimojiLength } from "./kumimoji.types.ts";
+import type { PartyGame, PartyPlayer, PartySeat, PartySettings } from "./party.types.ts";
+import { type TilePlay } from "./play.ts";
+/**
+ * PASS AND PLAY: two to eight people round one device. John, 2026-09-28:
+ * "after you finish your move, you say you're done and… the screen will cover
+ * until the next person comes… then they can see their tiles and they play the
+ * game and then it rotates."
+ *
+ * One bag for everybody, read as a line exactly as the solo game reads it
+ * (`play.ts`), and a hand and a table for each player. A player's turn is
+ * played with the solo game's own moves on a `TilePlay` made of the shared bag
+ * and their own hand and table (`seatPlay`), and put back (`withSeatPlay`), so
+ * laying, moving, swapping, sorting and trading are the one set of rules.
+ * What is only the party's is here — the deal, whose turn it is, and Draw for
+ * 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. */
+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. */
+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. */
+export declare function partyPlayersAsked(value: unknown): number;
+/**
+ * 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.
+ */
+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.
+ */
+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. */
+export declare function computerName(players: readonly PartyPlayer[]): string;
+/** Whether a computer plays this seat. */
+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. */
+export declare function tableTally(tiles: Tiles): string;
+/** A name as kept: trimmed, one line, and no longer than a line holds. */
+export declare function tidyName(name: string): string;
+/** What a player is called: their name, or "Player 2". */
+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. */
+export declare function seatPlay(game: PartyGame): TilePlay;
+/**
+ * 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.
+ */
+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. */
+export declare function withSeatPlay(game: PartyGame, play: TilePlay): PartyGame;
+/** Tiles still in the shared bag. */
+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. */
+export declare function stillIn(game: PartyGame): number[];
+/** The next player still in after `from`, round the table; `from` itself when nobody else is. */
+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.
+ */
+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.
+ */
+export declare function drawAll(game: PartyGame): PartyGame;
+/**
+ * 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.
+ */
+export declare function passViewStart(game: PartyGame): number;
+/** The player a swipe or an arrow shows next: `by` seats on, round the table. */
+export declare function stepView(game: PartyGame, from: number, by: number): number;

package/dist/party.js

@@ -0,0 +1,172 @@
+import { mayTrade, tilesLeft } from "./play.js";
+import { KUMIMOJI_PARTY, kumimojiTileCount } from "./tiles.constants.js";
+/**
+ * PASS AND PLAY: two to eight people round one device. John, 2026-09-28:
+ * "after you finish your move, you say you're done and… the screen will cover
+ * until the next person comes… then they can see their tiles and they play the
+ * game and then it rotates."
+ *
+ * One bag for everybody, read as a line exactly as the solo game reads it
+ * (`play.ts`), and a hand and a table for each player. A player's turn is
+ * played with the solo game's own moves on a `TilePlay` made of the shared bag
+ * and their own hand and table (`seatPlay`), and put back (`withSeatPlay`), so
+ * laying, moving, swapping, sorting and trading are the one set of rules.
+ * What is only the party's is here — the deal, whose turn it is, and Draw for
+ * 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. */
+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. */
+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. */
+export function partyPlayersAsked(value) {
+    const count = Number(value);
+    return Number.isInteger(count) && count >= KUMIMOJI_PARTY.least && count <= KUMIMOJI_PARTY.most ? count : 1;
+}
+const LENGTHS = ["short", "medium", "full"];
+/**
+ * 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.
+ */
+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.
+    if (players < KUMIMOJI_PARTY.least)
+        return chosen;
+    const fits = (length) => partyFits(players, hand, kumimojiTileCount(hand, length, undefined, doubleSet));
+    if (fits(chosen))
+        return chosen;
+    return LENGTHS.find(fits) ?? "full";
+}
+/**
+ * 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.
+ */
+export function startParty(settings, bag, seats) {
+    const count = Math.min(Math.max(seats.length, KUMIMOJI_PARTY.least), KUMIMOJI_PARTY.most);
+    const hand = settings.size;
+    if (bag.length < partyTilesNeeded(count, hand))
+        throw new Error(`A bag of ${bag.length} cannot be dealt to ${count} players.`);
+    const players = [];
+    for (let at = 0; at < count; at += 1) {
+        const seat = seats[at] ?? "";
+        const asked = typeof seat === "string" ? { name: seat } : seat;
+        const dealt = { hand: [...bag.slice(at * hand, (at + 1) * hand)], tiles: new Map() };
+        players.push(asked.computer === true ? { name: computerName(players), computer: true, ...dealt } : { name: tidyName(asked.name), ...dealt });
+    }
+    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. */
+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. */
+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. */
+export function tableTally(tiles) {
+    return [...tiles.values()].sort().join("");
+}
+/** A name as kept: trimmed, one line, and no longer than a line holds. */
+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". */
+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. */
+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 };
+}
+/**
+ * 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.
+ */
+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. */
+export function withSeatPlay(game, play) {
+    if (game.ending !== null)
+        return game;
+    if (game.traded && play.returned.length > game.returned.length)
+        return game;
+    const players = game.players.map((player, at) => (at === game.turn ? { ...player, hand: play.hand, tiles: play.tiles } : player));
+    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. */
+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. */
+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. */
+export function nextIn(game, from) {
+    const count = game.players.length;
+    for (let step = 1; step <= count; step += 1) {
+        const at = (from + step) % count;
+        if (!game.resigned.includes(at))
+            return at;
+    }
+    return 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.
+ */
+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;
+}
+/**
+ * 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.
+ */
+export function drawAll(game) {
+    const count = game.players.length;
+    const order = stillIn(game).sort((a, b) => ((a - game.turn + count) % count) - ((b - game.turn + count) % count));
+    if (partyTilesLeft(game) < order.length)
+        return game;
+    const coming = (game.bag + game.returned).slice(game.taken, game.taken + order.length);
+    const players = game.players.map((player, at) => (order.includes(at) ? { ...player, hand: [...player.hand, coming[order.indexOf(at)]] } : player));
+    return { ...game, taken: game.taken + order.length, players };
+}
+/**
+ * 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.
+ */
+export function passViewStart(game) {
+    return game.passedBy ?? game.turn;
+}
+/** The player a swipe or an arrow shows next: `by` seats on, round the table. */
+export function stepView(game, from, by) {
+    const count = game.players.length;
+    return (((from + by) % count) + count) % count;
+}

package/dist/party.types.d.ts

@@ -0,0 +1,86 @@
+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. */
+export type PartySettings = {
+    /** The hand each player is dealt: 7 Quick or 11 Classic (3 in the browser tests alone). */
+    size: number;
+    level: KumimojiLevel;
+    /** The seed the bag was made from; the bag itself is kept too, so a kept game never depends on the generator. */
+    seed: number;
+    gameLength: KumimojiLength;
+    language: KumimojiLanguage;
+    doubleSet: boolean;
+    /** Whether Diagonals was chosen: every table in the game is read along its diagonals too (`judgeGrid`). */
+    diagonals: boolean;
+    /** Whether Help was chosen on the set-up screen. */
+    hints: boolean;
+};
+/**
+ * One player: their name as typed (empty for "Player N"), their hand and
+ * 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.
+ */
+export type PartyPlayer = {
+    name: string;
+    hand: readonly string[];
+    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. */
+export type PartySeat = {
+    name: string;
+    computer?: boolean;
+};
+/**
+ * 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.
+ */
+export type PartyGame = {
+    settings: PartySettings;
+    /** The tiles in the order they come out. */
+    bag: string;
+    /** Tiles traded back, in order; they come out after the bag. */
+    returned: string;
+    /** How many tiles have been taken from `bag + returned`, by every player together. */
+    taken: number;
+    /** Up to eight; two to eight when dealt, and one or more after players leave (`partySeats.ts`). */
+    players: readonly PartyPlayer[];
+    /**
+     * How many the game was dealt to: the address's own `players`, which a
+     * kept game is matched to, however many have joined or left since.
+     */
+    dealt: number;
+    /** Whose turn it is, by place in `players`. */
+    turn: number;
+    /** How many turns have been ended, and seats left: a turn's own number, so each one opens on a fresh view. */
+    turns: number;
+    /** The players who went out, in the order they did; the first is the one who began the last round. */
+    out: readonly number[];
+    /**
+     * THE LAST ROUND: null until somebody goes out, then the players still to
+     * take their one last turn, in order. John, 2026-09-28: "once one person
+     * goes out the remaining players get one last move. That should make it
+     * fair."
+     */
+    lastTurns: readonly number[] | null;
+    /** The players who resigned, in the order they did: their turns are passed over from then on. */
+    resigned: readonly number[];
+    /** The resignations since a player still in last pressed Done: who is tied if nobody is left standing. */
+    resignRun: readonly number[];
+    /** How the game ended (`PartyEnding`), or null while it is played. */
+    ending: PartyEnding | null;
+    /** The tiles on the table of the player whose turn it is when the turn began, in order (`tableTally`): whether they have laid anything since. */
+    startTable: string;
+    /** Whether the player whose turn it is has traded this turn. */
+    traded: boolean;
+    /** Who played the turn before this one — pressed Done or resigned — or null before anybody has: whose table the pass screen opens on. */
+    passedBy: number | null;
+};
+/**
+ * HOW A PASS-AND-PLAY GAME ENDS. `out`: somebody went out and everybody else
+ * 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.
+ */
+export type PartyEnding = "out" | "standing" | "tied";

package/dist/party.types.js

@@ -0,0 +1 @@
+export {};

package/dist/partyKept.d.ts

@@ -0,0 +1,17 @@
+import type { PartyGame, PartySettings } from "./party.types.ts";
+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. */
+export declare function readSettings(value: unknown): PartySettings | null;
+/**
+ * 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.
+ */
+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. */
+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. */
+export declare function isPartyFor(game: PartyGame, settings: PartySettings, players: number): boolean;

package/dist/partyKept.js

@@ -0,0 +1,149 @@
+import { decodeGrid, encodeGrid, lettersOf, sameLetters } from "./grid.js";
+import { KUMIMOJI_PARTY, KUMIMOJI_HANDS } from "./tiles.constants.js";
+/**
+ * A PASS-AND-PLAY GAME KEPT IN THE BROWSER, as one string of JSON: the
+ * settings, the whole bag in its order, what was traded back and taken, whose
+ * turn it is, who is out, who resigned and who still has a last turn, what
+ * this turn has done so far, and every player's
+ * name, hand and grid (`encodeGrid`), and whether a computer plays it. The
+ * bag is written out rather than made again from the seed, so a game left half
+ * way opens the same after the generator has changed.
+ *
+ * Joining, leaving and computer players came after the first version of this
+ * and did not change its number: `dealt` and a player's `computer` are
+ * written only when they say something, and a game kept without them reads
+ * as one dealt to as many as sit at it, every seat a person's.
+ *
+ * It is never sent to the server: a local game has no points, no record and
+ * nothing to check, and the names in it are the players' own business.
+ */
+const VERSION = 1;
+export function encodeParty(game) {
+    const kept = {
+        v: VERSION,
+        settings: game.settings,
+        bag: game.bag,
+        returned: game.returned,
+        taken: game.taken,
+        turn: game.turn,
+        turns: game.turns,
+        out: [...game.out],
+        lastTurns: game.lastTurns === null ? null : [...game.lastTurns],
+        resigned: [...game.resigned],
+        resignRun: [...game.resignRun],
+        ending: game.ending,
+        startTable: game.startTable,
+        traded: game.traded,
+        passedBy: game.passedBy,
+        ...(game.dealt === game.players.length ? {} : { dealt: game.dealt }),
+        players: game.players.map((player) => ({ name: player.name, hand: player.hand.join(""), grid: encodeGrid(player.tiles), ...(player.computer === true ? { computer: true } : {}) })),
+    };
+    return JSON.stringify(kept);
+}
+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. */
+export function readSettings(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const s = value;
+    const sizes = Object.values(KUMIMOJI_HANDS);
+    if (!sizes.includes(s.size))
+        return null;
+    if (s.level !== "easy" && s.level !== "medium" && s.level !== "hard")
+        return null;
+    if (!Number.isInteger(s.seed))
+        return null;
+    if (s.gameLength !== "short" && s.gameLength !== "medium" && s.gameLength !== "full")
+        return null;
+    if (s.language !== "english" && s.language !== "japanese")
+        return null;
+    if (typeof s.doubleSet !== "boolean" || typeof s.hints !== "boolean")
+        return null;
+    // A game kept before Diagonals existed has no word for it, and was played without.
+    if (s.diagonals !== undefined && typeof s.diagonals !== "boolean")
+        return null;
+    return { size: s.size, level: s.level, seed: s.seed, gameLength: s.gameLength, language: s.language, doubleSet: s.doubleSet, diagonals: s.diagonals === true, hints: s.hints };
+}
+/**
+ * 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.
+ */
+export function decodeParty(code, familyKey) {
+    if (code === null)
+        return null;
+    let kept;
+    try {
+        kept = JSON.parse(code);
+    }
+    catch {
+        return null;
+    }
+    if (typeof kept !== "object" || kept === null || kept.v !== VERSION)
+        return null;
+    const settings = readSettings(kept.settings);
+    if (settings === null || !isTiles(kept.bag) || !isTiles(kept.returned))
+        return null;
+    const line = kept.bag + kept.returned;
+    if (!isCount(kept.taken, line.length) || !Array.isArray(kept.players))
+        return null;
+    const count = kept.players.length;
+    // Dealt to two or more; one may be left at the table after the rest leave (`partySeats.ts`).
+    if (count < 1 || count > KUMIMOJI_PARTY.most)
+        return null;
+    const dealt = kept.dealt ?? count;
+    if (!Number.isInteger(dealt) || dealt < KUMIMOJI_PARTY.least || dealt > KUMIMOJI_PARTY.most)
+        return null;
+    if (!isCount(kept.turn, count - 1) || !isCount(kept.turns, 1000000) || (kept.ending !== null && kept.ending !== "out" && kept.ending !== "standing" && kept.ending !== "tied") || typeof kept.traded !== "boolean" || !isTiles(kept.startTable) || (kept.passedBy !== null && !isCount(kept.passedBy, count - 1)))
+        return null;
+    const seats = (list) => Array.isArray(list) && list.every((at) => isCount(at, count - 1)) && new Set(list).size === list.length;
+    if (!seats(kept.out) || (kept.lastTurns !== null && !seats(kept.lastTurns)) || !seats(kept.resigned) || !seats(kept.resignRun))
+        return null;
+    const players = [];
+    for (const player of kept.players) {
+        if (typeof player !== "object" || player === null || typeof player.name !== "string" || player.name.length > KUMIMOJI_PARTY.nameMost || !isTiles(player.hand))
+            return null;
+        if (player.computer !== undefined && player.computer !== true)
+            return null;
+        const tiles = decodeGrid(player.grid);
+        if (tiles === null)
+            return null;
+        players.push(player.computer === true ? { name: player.name, hand: [...player.hand], tiles, computer: true } : { name: player.name, hand: [...player.hand], tiles });
+    }
+    const game = { settings, bag: kept.bag, returned: kept.returned, taken: kept.taken, players, dealt, turn: kept.turn, turns: kept.turns, out: kept.out, lastTurns: kept.lastTurns, resigned: kept.resigned, resignRun: kept.resignRun, ending: kept.ending, startTable: kept.startTable, traded: kept.traded, passedBy: kept.passedBy };
+    if (familyKey !== undefined && !holdsItsBag(game, familyKey))
+        return null;
+    return game;
+}
+/** Whether what everybody holds is exactly what was taken from the bag, less what was given back. */
+export function holdsItsBag(game, familyKey) {
+    const taken = [...(game.bag + game.returned).slice(0, game.taken)].map(familyKey);
+    const back = [...game.returned].map(familyKey);
+    const held = [...game.players.flatMap((player) => [...player.hand, ...player.tiles.values()])].map(familyKey);
+    if ([...taken, ...back, ...held].some((tile) => tile === null))
+        return false;
+    const tally = lettersOf(taken);
+    for (const tile of back)
+        tally.set(tile, (tally.get(tile) ?? 0) - 1);
+    for (const [tile, count] of tally)
+        if (count === 0)
+            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. */
+export function isPartyFor(game, settings, players) {
+    const a = game.settings;
+    return (game.dealt === players &&
+        a.size === settings.size &&
+        a.level === settings.level &&
+        a.seed === settings.seed &&
+        a.gameLength === settings.gameLength &&
+        a.language === settings.language &&
+        a.doubleSet === settings.doubleSet &&
+        a.diagonals === settings.diagonals &&
+        a.hints === settings.hints);
+}

package/dist/partySeats.d.ts

@@ -0,0 +1,53 @@
+import type { PartyGame, PartySeat } from "./party.types.ts";
+/**
+ * JUMPING IN AND OUT OF A PASS-AND-PLAY GAME. John, 2026-09-28: "People can
+ * jump in and out of a game at which point all their tiles go back to the
+ * pot. Also you can add computer bots."
+ *
+ * Both happen from the pass screen, between turns, never on somebody's desk.
+ * Pure, like every rule here: each returns a new game, or the one it was
+ * given where the change is refused.
+ *
+ * JOINING: a new player, or a computer, takes the next seat after the last
+ * and a hand of the game's size from the bag, and plays when the turn comes
+ * round to them. Offered while there are fewer than eight, the last round has
+ * not begun (a player who sat down then could never catch up, and would only
+ * be dealt tiles to lose with), and the bag holds a whole hand.
+ *
+ * LEAVING: every tile in the leaver's hand and on their table goes back into
+ * the bag, which is shuffled with them in, and play goes on with the next
+ * player. A player who has gone out has finished, and stays at the table until
+ * the game ends; and the last person at the table cannot leave it to the
+ * computers — they end the game instead.
+ *
+ * Fewer than two left is no new rule: the one still in is the last one
+ * standing (`lastStanding`), and wins by laying a tile on a sound grid, as
+ * when everybody else resigns — unless somebody joins first.
+ */
+/** Why nobody can join now, or null when a hand can be dealt. */
+export type JoinRefusal = "over" | "full" | "lastRound" | "bag";
+export declare function joinRefused(game: PartyGame): JoinRefusal | null;
+/** A player, or a computer, sat down after the last seat with the next hand out of the bag. */
+export declare function joinParty(game: PartyGame, seat: PartySeat): PartyGame;
+/** Why this player cannot leave now, or null when they can. */
+export type LeaveRefusal = "over" | "out" | "lastPerson";
+export declare function leaveRefused(game: PartyGame, at: number): LeaveRefusal | null;
+/** How many tiles a player would put back in the bag by leaving: their hand and their table. */
+export declare function tilesHeldBy(game: PartyGame, at: number): number;
+/**
+ * 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.
+ *
+ * The bag is kept as a line whose first `taken` tiles are the ones held, less
+ * what was traded back (`holdsItsBag`); after a leave it is written afresh as
+ * exactly that: the tiles everybody still holds, then the shuffled rest, with
+ * nothing traded back. Every seat after the leaver's moves up one, and the
+ * unnamed players keep the names they were shown ("Player 3" stays Player 3).
+ *
+ * If it was their turn, the turn passes to the next still in, or in the last
+ * round to the next still to have their last turn; a last round with nobody
+ * left to play ends. With nobody still in — everybody left has resigned —
+ * the game ends tied between them.
+ */
+export declare function leaveParty(game: PartyGame, at: number): PartyGame;