@johnmorrisdotca/kumimoji 1.0.1

package/dist/partySeats.js

@@ -0,0 +1,119 @@
+import { seededRandom, shuffled } from "./random.js";
+import { computerName, isComputer, nextIn, partyTilesLeft, stillIn, tableTally, tidyName } from "./party.js";
+import { tileFace } from "./tileFace.js";
+import { KUMIMOJI_PARTY } from "./tiles.constants.js";
+export function joinRefused(game) {
+    if (game.ending !== null)
+        return "over";
+    if (game.players.length >= KUMIMOJI_PARTY.most)
+        return "full";
+    if (game.lastTurns !== null)
+        return "lastRound";
+    if (partyTilesLeft(game) < game.settings.size)
+        return "bag";
+    return null;
+}
+/** A player, or a computer, sat down after the last seat with the next hand out of the bag. */
+export function joinParty(game, seat) {
+    if (joinRefused(game) !== null)
+        return game;
+    const hand = [...(game.bag + game.returned).slice(game.taken, game.taken + game.settings.size)];
+    const tiles = new Map();
+    const player = seat.computer === true ? { name: computerName(game.players), computer: true, hand, tiles } : { name: tidyName(seat.name) || freePlayerName(game.players), hand, tiles };
+    return { ...game, players: [...game.players, player], taken: game.taken + hand.length };
+}
+/** "Player" and the next seat's number, or the lowest number nobody at the table goes by. */
+function freePlayerName(players) {
+    const taken = new Set(players.map((player, at) => player.name || `Player ${at + 1}`));
+    const next = `Player ${players.length + 1}`;
+    if (!taken.has(next))
+        return next;
+    for (let number = 1;; number += 1)
+        if (!taken.has(`Player ${number}`))
+            return `Player ${number}`;
+}
+export function leaveRefused(game, at) {
+    if (game.ending !== null || game.players[at] === undefined)
+        return "over";
+    if (game.out.includes(at))
+        return "out";
+    if (!isComputer(game, at) && game.players.filter((player) => player.computer !== true).length <= 1)
+        return "lastPerson";
+    return null;
+}
+/** How many tiles a player would put back in the bag by leaving: their hand and their table. */
+export function tilesHeldBy(game, at) {
+    const player = game.players[at];
+    return player === undefined ? 0 : player.hand.length + player.tiles.size;
+}
+/**
+ * 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 function leaveParty(game, at) {
+    if (leaveRefused(game, at) !== null)
+        return game;
+    const leaver = game.players[at];
+    const back = [...leaver.hand, ...leaver.tiles.values()].map((tile) => (tileFace(tile).wild ? "*" : tile));
+    const players = game.players.flatMap((player, seat) => (seat === at ? [] : [{ ...player, name: player.name || `Player ${seat + 1}` }]));
+    const seatOf = (seat) => (seat > at ? seat - 1 : seat);
+    const without = (seats) => seats.filter((seat) => seat !== at).map(seatOf);
+    const held = players.flatMap((player) => [...player.hand, ...player.tiles.values()]);
+    const rest = [...(game.bag + game.returned).slice(game.taken), ...back];
+    const pot = shuffled(rest, seededRandom(potSeed(game)));
+    const lastTurns = game.lastTurns === null ? null : without(game.lastTurns);
+    let turn = seatOf(game.turn);
+    let ending = null;
+    if (at === game.turn) {
+        if (lastTurns !== null) {
+            // The leaver was first of the last round's list: the next on it plays, or the round is over.
+            if (lastTurns.length > 0)
+                turn = lastTurns[0];
+            else {
+                turn = seatOf(game.out[0] ?? 0);
+                ending = "out";
+            }
+        }
+        else {
+            const next = nextIn(game, at);
+            turn = next === at ? 0 : seatOf(next);
+        }
+    }
+    const after = {
+        ...game,
+        bag: held.join("") + pot.join(""),
+        returned: "",
+        taken: held.length,
+        players,
+        turn,
+        turns: game.turns + 1,
+        out: without(game.out),
+        lastTurns,
+        resigned: without(game.resigned),
+        resignRun: without(game.resignRun),
+        ending,
+        passedBy: game.passedBy === null || game.passedBy === at ? null : seatOf(game.passedBy),
+    };
+    const moved = at === game.turn ? { startTable: tableTally(players[turn].tiles), traded: false } : {};
+    if (ending === null && lastTurns === null && stillIn(after).length === 0) {
+        // Only players who resigned are left: tied, the last run of them, or all of them where that run has left.
+        return { ...after, ...moved, ending: "tied", resignRun: after.resignRun.length > 0 ? after.resignRun : after.resigned };
+    }
+    return { ...after, ...moved };
+}
+/** The seed a leave shuffles with: the game's own, stirred by how far it has gone. */
+function potSeed(game) {
+    return (game.settings.seed ^ Math.imul(game.turns + 1, 0x9e3779b1) ^ Math.imul(game.taken + 1, 0x85ebca6b)) >>> 0;
+}

package/dist/partyTurns.d.ts

@@ -0,0 +1,75 @@
+import type { GridVerdict } from "./grid.ts";
+import type { PartyGame } from "./party.types.ts";
+import type { TileWords } from "./tileWords.ts";
+/**
+ * HOW A PASS-AND-PLAY TURN ENDS, AND HOW THE GAME DOES: Done, going out, the
+ * last round, resigning, and who won. The rules of the table itself are the
+ * 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. */
+export declare function isOver(game: PartyGame): boolean;
+/**
+ * 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.
+ */
+export declare function goesOut(game: PartyGame, verdict: GridVerdict): boolean;
+/** Whether the player whose turn it is has laid a tile on their table this turn: more tiles there than when it began. */
+export declare function laidThisTurn(game: PartyGame): boolean;
+/** Whether the player whose turn it is is the only one still in: everybody else has resigned. */
+export declare function lastStanding(game: PartyGame): boolean;
+/**
+ * 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`).
+ */
+export declare function mustTradeFirst(game: PartyGame, handSpells: (hand: readonly string[]) => boolean): boolean;
+/** 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. */
+export declare function handCanSpell(hand: readonly string[], words: TileWords): boolean;
+/**
+ * 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).
+ */
+export declare function doneRefused(game: PartyGame, verdict: GridVerdict, handSpells: (hand: readonly string[]) => boolean): "trade" | "standing" | null;
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function endTurn(game: PartyGame, verdict: GridVerdict, handSpells: (hand: readonly string[]) => boolean): PartyGame;
+/**
+ * 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."
+ */
+export declare function mayResign(game: PartyGame): boolean;
+/**
+ * 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."
+ */
+export declare function resign(game: PartyGame): PartyGame;
+/**
+ * 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.
+ */
+export declare function winnersOf(game: PartyGame): readonly number[];
+/** Whether the turn now being played is a player's last. */
+export declare function isLastTurn(game: PartyGame): boolean;

package/dist/partyTurns.js

@@ -0,0 +1,153 @@
+import { wordsInHand } from "./help.js";
+import { nextIn, partyTilesLeft, seatPlay, stillIn, tableTally } from "./party.js";
+import { mayTrade } from "./play.js";
+import { KUMIMOJI_TRADE } from "./tiles.constants.js";
+/**
+ * HOW A PASS-AND-PLAY TURN ENDS, AND HOW THE GAME DOES: Done, going out, the
+ * last round, resigning, and who won. The rules of the table itself are the
+ * 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. */
+export function isOver(game) {
+    return game.ending !== null;
+}
+/**
+ * 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.
+ */
+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. */
+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. */
+export function lastStanding(game) {
+    return !isOver(game) && game.lastTurns === null && stillIn(game).length === 1;
+}
+/**
+ * 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`).
+ */
+export function mustTradeFirst(game, handSpells) {
+    if (isOver(game) || game.traded)
+        return false;
+    const play = seatPlay(game);
+    if (play.hand.length === 0 || tableTally(play.tiles) !== game.startTable || !mayTrade(play))
+        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. */
+export function handCanSpell(hand, words) {
+    return hand.some(words.isWild) || wordsInHand(hand, words).length > 0;
+}
+/**
+ * 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).
+ */
+export function doneRefused(game, verdict, handSpells) {
+    if (mustTradeFirst(game, handSpells))
+        return "trade";
+    const used = game.players[game.turn].hand.length === 0;
+    if (lastStanding(game) && !(verdict.sound && (laidThisTurn(game) || used)))
+        return "standing";
+    return null;
+}
+/** The game passed to `turn`, a new turn with nothing traded and its table as it stands. */
+function passTo(game, turn, rest) {
+    return { ...game, ...rest, turns: game.turns + 1, turn, traded: false, startTable: tableTally(game.players[turn].tiles), passedBy: game.turn };
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function endTurn(game, verdict, handSpells) {
+    if (isOver(game) || doneRefused(game, verdict, handSpells) !== null)
+        return game;
+    if (lastStanding(game))
+        return passTo(game, game.turn, { ending: "standing", resignRun: [] });
+    const out = goesOut(game, verdict) ? [...game.out, game.turn] : game.out;
+    if (game.lastTurns === null) {
+        if (out.length === 0)
+            return passTo(game, nextIn(game, game.turn), { resignRun: [] });
+        const lastTurns = stillIn(game).filter((at) => at !== game.turn).sort((a, b) => fromTurn(game, a) - fromTurn(game, b));
+        if (lastTurns.length === 0)
+            return passTo(game, game.turn, { out, lastTurns, ending: "out" });
+        return passTo(game, lastTurns[0], { out, lastTurns, resignRun: [] });
+    }
+    return nextLastTurn(game, out);
+}
+/** How far round the table from the player whose turn it is. */
+function fromTurn(game, at) {
+    return (at - game.turn + game.players.length) % game.players.length;
+}
+/** The last round moved on past the player whose turn it was: to the next still to play, or the end. */
+function nextLastTurn(game, out, rest = {}) {
+    const lastTurns = (game.lastTurns ?? []).filter((at) => at !== game.turn);
+    if (lastTurns.length === 0)
+        return passTo(game, game.turn, { ...rest, out, lastTurns, ending: "out" });
+    return passTo(game, lastTurns[0], { ...rest, out, lastTurns });
+}
+/**
+ * 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."
+ */
+export function mayResign(game) {
+    return !isOver(game) && partyTilesLeft(game) < KUMIMOJI_TRADE.take;
+}
+/**
+ * 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."
+ */
+export function resign(game) {
+    if (!mayResign(game))
+        return game;
+    const resigned = [...game.resigned, game.turn];
+    const resignRun = [...game.resignRun, game.turn];
+    const after = { ...game, resigned, resignRun };
+    if (game.lastTurns !== null)
+        return nextLastTurn(after, game.out);
+    if (stillIn(after).length === 0)
+        return passTo(after, game.turn, { ending: "tied" });
+    return passTo(after, nextIn(after, game.turn), {});
+}
+/**
+ * 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.
+ */
+export function winnersOf(game) {
+    if (game.ending === "out")
+        return game.out;
+    if (game.ending === "standing")
+        return stillIn(game);
+    if (game.ending === "tied")
+        return game.resignRun;
+    return [];
+}
+/** Whether the turn now being played is a player's last. */
+export function isLastTurn(game) {
+    return !isOver(game) && game.lastTurns !== null;
+}

package/dist/placement.d.ts

@@ -0,0 +1,26 @@
+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. */
+export type CrossingFit = {
+    first: Square;
+    fresh: Square[];
+};
+/**
+ * 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`).
+ */
+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;
+/**
+ * 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.
+ */
+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

@@ -0,0 +1,87 @@
+/**
+ * WHERE A WORD CAN CROSS A CROSSWORD WITHOUT SPOILING IT: the one rule the
+ * generator lays its bags by (`generate.ts`) and the computer player lays its
+ * own table by (`computerPlay.ts`), written once.
+ *
+ * A word laid across or down through a tile already down, with nothing at
+ * either end of it and no new tile touching anything at its sides, makes one
+ * new run — the word itself — and leaves every other run as it was. So on a
+ * grid that was sound, the grid after it is sound too: that is what lets the
+ * generator promise every bag can be finished, and what keeps the computer
+ * from ever leaving a misspelt table.
+ *
+ * With DIAGONALS (`diagonalWord`), a new tile may also make or lengthen a
+ * diagonal run of three or more (`DIAGONAL_RUN_LEAST`), which is then read
+ * too; a word is laid only where each such run is a word, so a sound grid
+ * stays sound under that rule as well.
+ *
+ * Pure, and blind to what the squares are kept in: the caller answers what
+ * letter stands at a square (`""` for none) and whether a square may be used
+ * at all, so the generator's fixed laying square and the computer's table
+ * with no edges ask the same question.
+ */
+import { DIAGONAL_RUN_LEAST } from "./grid.js";
+/**
+ * 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`).
+ */
+export function crossingFit(letterAt, inside, word, anchor, at, across, diagonalWord = null) {
+    const dr = across ? 0 : 1;
+    const dc = across ? 1 : 0;
+    const row = anchor.row - at * dr;
+    const col = anchor.col - at * dc;
+    const length = word.length;
+    if (!inside(row, col) || !inside(row + (length - 1) * dr, col + (length - 1) * dc))
+        return null;
+    const taken = (r, c) => inside(r, c) && letterAt(r, c) !== "";
+    if (taken(row - dr, col - dc) || taken(row + length * dr, col + length * dc))
+        return null;
+    const fresh = [];
+    for (let k = 0; k < length; k += 1) {
+        const r = row + k * dr;
+        const c = col + k * dc;
+        const there = letterAt(r, c);
+        if (there !== "") {
+            if (there !== word[k])
+                return null;
+            continue;
+        }
+        // Its sides: above and below a word across, left and right of one down.
+        if (taken(r - dc, c - dr) || taken(r + dc, c + dr))
+            return null;
+        fresh.push({ row: r, col: c });
+    }
+    if (fresh.length === 0)
+        return null;
+    if (diagonalWord !== null && !diagonalsRead(letterAt, inside, word, { first: { row, col }, fresh }, diagonalWord))
+        return null;
+    return { first: { row, col }, fresh };
+}
+/**
+ * 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.
+ */
+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)]]));
+    const at = (row, col) => (inside(row, col) ? letterAt(row, col) || (freshAt.get(`${row},${col}`) ?? "") : "");
+    for (const { row, col } of fit.fresh) {
+        for (const lean of [1, -1]) {
+            let top = 0;
+            while (at(row - top - 1, col - (top + 1) * lean) !== "")
+                top += 1;
+            let run = "";
+            for (let step = -top; at(row + step, col + step * lean) !== ""; step += 1)
+                run += at(row + step, col + step * lean);
+            if (run.length >= DIAGONAL_RUN_LEAST && !isWord(run))
+                return false;
+        }
+    }
+    return true;
+}

package/dist/play.d.ts

@@ -0,0 +1,76 @@
+import { type GridVerdict, type Tiles } from "./grid.ts";
+/**
+ * A KUMIMOJI BEING PLAYED: the bag, the tiles traded back into it, how many
+ * have been taken out, the tiles on the table and the hand. Every move is a
+ * function that returns a new state and leaves the one it was given alone,
+ * the way the engine's moves are. Nothing here knows how the table is being
+ * looked at — zoom and pan are the view's (`tableView.ts`), never the game's.
+ *
+ * THE BAG IS A LINE, not a heap. Its tiles come out in the order the seed dealt
+ * them (`givens`), and a tile traded back joins the END of the line, so the
+ * tiles still to come are always `bag + returned` from `taken` on. That keeps
+ * a game the same for everybody at a seed, trades and all, and lets a kept
+ * game be checked: what is held — hand and table — is exactly what was taken,
+ * less what was given back.
+ */
+export type TilePlay = {
+    /** The tiles in the order they come out: the puzzle's givens. */
+    bag: string;
+    /** Tiles traded back, in order; they come out after the bag. */
+    returned: string;
+    /** How many tiles have been taken from `bag + returned`. */
+    taken: number;
+    /** The tiles on the table, by square ("row,col"). */
+    tiles: Tiles;
+    /** The hand, in the order the player keeps it. */
+    hand: readonly string[];
+};
+/** The opening hand: the first `handSize` tiles of the bag, and an empty table. */
+export declare function deal(bag: string, handSize: number): TilePlay;
+/** How many tiles are still in the bag. */
+export declare function tilesLeft(play: TilePlay): number;
+/** A tile from the hand onto an empty square. */
+export declare function placeFromHand(play: TilePlay, handAt: number, square: string): TilePlay;
+/** Give a hand tile its chosen reading, without changing which physical tile it is. */
+export declare function assignHandTile(play: TilePlay, handAt: number, face: string): TilePlay;
+/** Give a tile on the table its chosen reading, without changing its square. */
+export declare function assignTableTile(play: TilePlay, square: string, face: string): TilePlay;
+/** A tile on the table to another square: to an empty one it moves, onto a tile the two change places. */
+export declare function moveOnTable(play: TilePlay, from: string, to: string): TilePlay;
+/** A tile from the hand onto a square that holds one: they change places, the table's tile going to the hand where the other was. */
+export declare function swapWithHand(play: TilePlay, handAt: number, square: string): TilePlay;
+/** A tile on the table back to the end of the hand. */
+export declare function liftToHand(play: TilePlay, square: string): TilePlay;
+/** Every tile on the table back to the hand. */
+export declare function liftAll(play: TilePlay): TilePlay;
+/**
+ * The hand in order (John, 2026-09-28: "it gets sorted for letters
+ * alphabetically"): English A to Z, Japanese あいうえお, which is the order
+ * of the kana's tile codes, and the wilds last as they came.
+ */
+export declare function sortHand(play: TilePlay): TilePlay;
+/** Whether Draw may be pressed: the hand used, the grid sound, and a tile left to draw. */
+export declare function mayDraw(play: TilePlay, verdict: GridVerdict): boolean;
+/** The next tile or tiles out of the bag into the hand. */
+export declare function draw(play: TilePlay, count?: number): TilePlay;
+/** Whether a trade may be made: the bag holds as many as a trade takes. */
+export declare function mayTrade(play: TilePlay): boolean;
+/** One tile from the hand to the bottom of the bag, and the next three out of it. */
+export declare function trade(play: TilePlay, handAt: number): TilePlay;
+/** Whether the game is over: the bag empty, the hand used, and the grid sound. */
+export declare function isFinished(play: TilePlay, verdict: GridVerdict): boolean;
+export declare function encodeTileProgress(play: TilePlay): string;
+/** The parts of a kept game, or null for a string that is not one: its shape only, with no bag to check it against. */
+export declare function readTileProgress(code: string): {
+    taken: number;
+    returned: string;
+    hand: string[];
+    tiles: Map<string, string>;
+} | null;
+/**
+ * A kept game opened again on its own bag, or null where it does not belong
+ * to it: every tile held — hand and table — must be one taken from the bag
+ * and not given back. Null opens the game fresh rather than on a grid that
+ * never came out of this bag.
+ */
+export declare function decodeTileProgress(code: string, bag: string, language?: "english" | "japanese"): TilePlay | null;