@johnmorrisdotca/kumimoji 1.0.1 → 1.1.1

package/dist/computerTurn.d.ts

@@ -26,6 +26,7 @@ import type { TileWords } from "./tileWords.ts";
  */
 /** The most things a computer does in one turn before pressing Done: at the page's pause, a turn of about three seconds. */
 export declare const COMPUTER_STEPS_MOST = 8;
+/** A computer seat's whole turn as its steps, in order, for a page to show one at a time. None when it is not a computer's turn or the game is over. */
 export declare function planComputerTurn(game: PartyGame, words: TileWords): ComputerStep[];
 /** The game a computer's turn passes on: its plan's last step, or the game as it was where there is nothing to play. */
 export declare function afterComputerTurn(game: PartyGame, words: TileWords): PartyGame;

package/dist/computerTurn.js

@@ -29,6 +29,7 @@ import { liftAll, mayTrade, trade } from "./play.js";
 export const COMPUTER_STEPS_MOST = 8;
 /** How many settling steps may be needed at the end to be allowed Done at all; one trade a turn and a hand of tiles, so it is bounded anyway. */
 const SETTLING_MOST = 200;
+/** A computer seat's whole turn as its steps, in order, for a page to show one at a time. None when it is not a computer's turn or the game is over. */
 export function planComputerTurn(game, words) {
     const steps = [];
     if (game.ending !== null || !isComputer(game, game.turn))

package/dist/export.d.ts

@@ -0,0 +1,87 @@
+import { type Tiles } from "./grid.ts";
+import type { KumimojiDeal, KumimojiLanguage, KumimojiLength, KumimojiLevel } from "./kumimoji.types.ts";
+import { type TilePlay } from "./play.ts";
+import { type KumimojiStrings } from "./strings.ts";
+/**
+ * A GAME WRITTEN OUT for other programs and for people: JSON that reads back
+ * in, and plain text for a chat or a note. Both pure: a game in, a string
+ * out. What is done with the string (a file, a clipboard, a server) is the
+ * caller's.
+ *
+ * What is written is how the game was set up, its seed, and where the player
+ * has got to; never the bag, which the seed deals again. So `kumimojiFromJSON`
+ * trusts nothing in a file: it deals the bag from the seed itself, and opens
+ * the game only if every tile in the hand and on the table is one that came
+ * out of that bag and was not given back.
+ */
+/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one. */
+export declare const KUMIMOJI_EXPORT_FORMAT = 1;
+/** A game alone as it is kept: the deal, where the player has got to, and the time spent so far. */
+export type KumimojiSaved = {
+    /** The game as dealt: `generateKumimoji`'s. */
+    deal: KumimojiDeal;
+    /** Where the player has got to. */
+    play: TilePlay;
+    /** Milliseconds spent on it so far. */
+    elapsedMs: number;
+};
+/** A whole JSON export of one game: what `kumimojiToJSON` writes and `kumimojiFromJSON` reads. */
+export type KumimojiExported = {
+    /** The shape's number: `KUMIMOJI_EXPORT_FORMAT`. */
+    format: typeof KUMIMOJI_EXPORT_FORMAT;
+    /** Always `"kumimoji"`, so a file of this shape is not mistaken for another game's. */
+    game: "kumimoji";
+    /** The package and version that wrote it, such as `"kumimoji 1.1.0"`. For people; never read back. */
+    generator: string;
+    /** The opening hand: 3, 7 or 11. */
+    size: number;
+    /** How many of the tiles are wild. */
+    level: KumimojiLevel;
+    /** The seed the bag is dealt from. */
+    seed: number;
+    /** The language of the tiles. */
+    language: KumimojiLanguage;
+    /** How much of the set the bag holds. */
+    gameLength: KumimojiLength;
+    /** Two English sets at once. */
+    doubleSet: boolean;
+    /** Whether diagonal runs of three or more must be words too. */
+    diagonals: boolean;
+    /** Where the player has got to, as `encodeTileProgress` writes it: tiles taken, tiles traded back, the hand, the grid. */
+    progress: string;
+    /** Milliseconds spent so far. */
+    elapsedMs: number;
+};
+/** A game as the JSON export's object. */
+export declare function kumimojiExported(saved: KumimojiSaved): KumimojiExported;
+/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back. */
+export declare function kumimojiToJSON(saved: KumimojiSaved): string;
+/**
+ * A game from JSON that `kumimojiToJSON` wrote. Nothing in it is trusted: the
+ * bag is dealt again from the seed, and the game opens only if every tile held
+ * is one that came out of that bag. Resolves to null when the text is not
+ * JSON, is of a later format than this version reads, is another game's, or
+ * holds a hand or a grid that this bag never dealt.
+ *
+ * The word list of the game's language is loaded first, since dealing needs
+ * it; where there is no browser, import `@johnmorrisdotca/kumimoji/words`
+ * once, or the promise is rejected as `loadTileWords` rejects it.
+ */
+export declare function kumimojiFromJSON(text: string): Promise<KumimojiSaved | null>;
+/** A time as minutes and seconds: `1:05`. */
+export declare function kumimojiClock(ms: number): string;
+/**
+ * A grid as lines of text, the way it lies on the table: English letters in
+ * capitals with a space between squares and a dot for an empty one, kana side
+ * by side with a full-width dot for an empty one, so that either lines up in a
+ * fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ */
+export declare function gridToText(tiles: Tiles, language?: KumimojiLanguage): string;
+/**
+ * A game as plain text, for a chat or a note: how it was set up, the
+ * crossword as it lies, the hand, how many tiles are left, and the time. In
+ * English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The
+ * word list of the game's language must have been loaded, as for any judging.
+ * Lines end with a line feed.
+ */
+export declare function kumimojiToText(saved: KumimojiSaved, strings?: KumimojiStrings): string;

package/dist/export.js

@@ -0,0 +1,158 @@
+import { boundsOf, squareAt } from "./grid.js";
+import { generateKumimoji } from "./generate.js";
+import { judgeWithWords } from "./judge.js";
+import { decodeTileProgress, encodeTileProgress, isFinished, tilesLeft } from "./play.js";
+import { KUMIMOJI_STRINGS, kumimojiSay } from "./strings.js";
+import { tileFace } from "./tileFace.js";
+import { KUMIMOJI_BAG } from "./tiles.constants.js";
+import { loadTileWords, tileWords } from "./tileWords.js";
+import { KUMIMOJI_VERSION } from "./version.js";
+/**
+ * A GAME WRITTEN OUT for other programs and for people: JSON that reads back
+ * in, and plain text for a chat or a note. Both pure: a game in, a string
+ * out. What is done with the string (a file, a clipboard, a server) is the
+ * caller's.
+ *
+ * What is written is how the game was set up, its seed, and where the player
+ * has got to; never the bag, which the seed deals again. So `kumimojiFromJSON`
+ * trusts nothing in a file: it deals the bag from the seed itself, and opens
+ * the game only if every tile in the hand and on the table is one that came
+ * out of that bag and was not given back.
+ */
+/** The shape of the JSON this package writes. It goes up only when a reader of the old shape would be wrong about the new one. */
+export const KUMIMOJI_EXPORT_FORMAT = 1;
+/** A game as the JSON export's object. */
+export function kumimojiExported(saved) {
+    const { deal, play } = saved;
+    return {
+        format: KUMIMOJI_EXPORT_FORMAT,
+        game: "kumimoji",
+        generator: `kumimoji ${KUMIMOJI_VERSION}`,
+        size: deal.size,
+        level: deal.level,
+        seed: deal.seed,
+        language: deal.language,
+        gameLength: deal.gameLength,
+        doubleSet: deal.doubleSet,
+        diagonals: deal.diagonals === true,
+        progress: encodeTileProgress(play),
+        elapsedMs: Math.max(0, Math.round(saved.elapsedMs)),
+    };
+}
+/** A game as JSON, two spaces deep, with the format's number first. `kumimojiFromJSON` reads it back. */
+export function kumimojiToJSON(saved) {
+    return `${JSON.stringify(kumimojiExported(saved), null, 2)}\n`;
+}
+const LEVELS = ["easy", "medium", "hard"];
+const LENGTHS_KEPT = ["short", "medium", "full"];
+/** The longest progress a game of two full sets could write, with room to spare: anything longer is not read. */
+const PROGRESS_MOST = 4000;
+/**
+ * A game from JSON that `kumimojiToJSON` wrote. Nothing in it is trusted: the
+ * bag is dealt again from the seed, and the game opens only if every tile held
+ * is one that came out of that bag. Resolves to null when the text is not
+ * JSON, is of a later format than this version reads, is another game's, or
+ * holds a hand or a grid that this bag never dealt.
+ *
+ * The word list of the game's language is loaded first, since dealing needs
+ * it; where there is no browser, import `@johnmorrisdotca/kumimoji/words`
+ * once, or the promise is rejected as `loadTileWords` rejects it.
+ */
+export async function kumimojiFromJSON(text) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof data !== "object" || data === null || Array.isArray(data))
+        return null;
+    const { format, game, size, level, seed, language, gameLength, doubleSet, diagonals, progress, elapsedMs } = data;
+    if (typeof format !== "number" || !Number.isInteger(format) || format < 1 || format > KUMIMOJI_EXPORT_FORMAT)
+        return null;
+    if (game !== "kumimoji")
+        return null;
+    if (typeof size !== "number" || KUMIMOJI_BAG[size] === undefined)
+        return null;
+    if (typeof level !== "string" || !LEVELS.includes(level))
+        return null;
+    if (typeof seed !== "number" || !Number.isInteger(seed) || seed < 0 || seed > 0xffffffff)
+        return null;
+    if (language !== "english" && language !== "japanese")
+        return null;
+    if (typeof gameLength !== "string" || !LENGTHS_KEPT.includes(gameLength))
+        return null;
+    if (typeof doubleSet !== "boolean" || typeof diagonals !== "boolean")
+        return null;
+    // Two sets are English's alone: the Japanese set is dealt once.
+    if (doubleSet && language !== "english")
+        return null;
+    if (typeof progress !== "string" || progress.length > PROGRESS_MOST)
+        return null;
+    const spent = typeof elapsedMs === "number" && Number.isFinite(elapsedMs) && elapsedMs >= 0 ? elapsedMs : 0;
+    await loadTileWords(language);
+    let deal;
+    try {
+        deal = generateKumimoji(size, level, seed, { language, gameLength: gameLength, doubleSet, diagonals });
+    }
+    catch {
+        return null;
+    }
+    const play = decodeTileProgress(progress, deal.givens, language);
+    return play === null ? null : { deal, play, elapsedMs: spent };
+}
+/** A time as minutes and seconds: `1:05`. */
+export function kumimojiClock(ms) {
+    const seconds = Math.max(0, Math.floor(ms / 1000));
+    return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+}
+/**
+ * A grid as lines of text, the way it lies on the table: English letters in
+ * capitals with a space between squares and a dot for an empty one, kana side
+ * by side with a full-width dot for an empty one, so that either lines up in a
+ * fixed-width face, every row as wide as the crossword. A wild that has been given nothing is `*`. No tiles is "".
+ */
+export function gridToText(tiles, language = "english") {
+    const bounds = boundsOf(tiles);
+    if (bounds === null)
+        return "";
+    const kana = language === "japanese";
+    const rows = [];
+    for (let row = bounds.top; row <= bounds.bottom; row += 1) {
+        const cells = [];
+        for (let col = bounds.left; col <= bounds.right; col += 1) {
+            const tile = tiles.get(squareAt(row, col));
+            if (tile === undefined)
+                cells.push(kana ? "・" : ".");
+            else {
+                const face = tileFace(tile);
+                cells.push(face.blank ? (kana ? "＊" : "*") : kana ? face.glyph : face.glyph.toUpperCase());
+            }
+        }
+        rows.push(cells.join(kana ? "" : " "));
+    }
+    return rows.join("\n");
+}
+/**
+ * A game as plain text, for a chat or a note: how it was set up, the
+ * crossword as it lies, the hand, how many tiles are left, and the time. In
+ * English unless given another table of strings (`KUMIMOJI_STRINGS.ja`). The
+ * word list of the game's language must have been loaded, as for any judging.
+ * Lines end with a line feed.
+ */
+export function kumimojiToText(saved, strings = KUMIMOJI_STRINGS.en) {
+    const { deal, play } = saved;
+    const words = tileWords(deal.language);
+    const face = (tile) => (tileFace(tile).blank ? "*" : deal.language === "japanese" ? words.glyphOf(tile) : words.glyphOf(tile).toUpperCase());
+    const lines = [kumimojiSay(strings.textTitle, { language: deal.language === "japanese" ? strings.japanese : strings.english, hand: deal.size, seed: deal.seed })];
+    lines.push(play.tiles.size === 0 ? strings.textEmpty : gridToText(play.tiles, deal.language));
+    if (isFinished(play, judgeWithWords(play.tiles, words, { diagonals: deal.diagonals === true })))
+        lines.push(strings.textFinished);
+    else {
+        lines.push(play.hand.length === 0 ? strings.textHandEmpty : kumimojiSay(strings.textHand, { tiles: play.hand.map(face).join(" ") }));
+        lines.push(kumimojiSay(strings.textLeft, { n: tilesLeft(play) }));
+    }
+    lines.push(kumimojiSay(strings.textTime, { time: kumimojiClock(saved.elapsedMs) }));
+    return `${lines.join("\n")}\n`;
+}

package/dist/grid.d.ts

@@ -20,14 +20,16 @@ export declare function placeOf(square: string): {
     row: number;
     col: number;
 };
-/** The rows and columns the tiles stand within, or null for no tiles. */
+/** The rows and columns a grid's tiles stand within. */
 export type Bounds = {
     top: number;
     left: number;
     bottom: number;
     right: number;
 };
+/** The rows and columns the tiles stand within, or null for no tiles. */
 export declare function boundsOf(tiles: Tiles): Bounds | null;
+/** A grid as a string, drawn from its own top-left tile: `cat/2o/2w`. `decodeGrid` reads it back. */
 export declare function encodeGrid(tiles: Tiles): string;
 /**
  * A grid read back, its first row at row 0, or null for anything that is not
@@ -94,4 +96,5 @@ export type GridVerdict = {
     /** The runs that are not words, as spelled, for the line under the table. */
     notWords: readonly string[];
 };
+/** A grid judged against any test of a word: `isWord` answers for a run as spelt, and `readable` says how to name one that is not. `judgeWithWords` is this with a language's list. */
 export declare function judgeGrid(tiles: Tiles, isWord: (word: string) => boolean, readable?: (word: string) => string, rules?: GridRules): GridVerdict;

package/dist/grid.js

@@ -8,6 +8,7 @@ export function placeOf(square) {
     const [row, col] = square.split(",").map(Number);
     return { row: row, col: col };
 }
+/** The rows and columns the tiles stand within, or null for no tiles. */
 export function boundsOf(tiles) {
     let bounds = null;
     for (const square of tiles.keys()) {
@@ -19,6 +20,7 @@ export function boundsOf(tiles) {
     }
     return bounds;
 }
+/** A grid as a string, drawn from its own top-left tile: `cat/2o/2w`. `decodeGrid` reads it back. */
 export function encodeGrid(tiles) {
     const bounds = boundsOf(tiles);
     if (bounds === null)
@@ -191,6 +193,7 @@ export function groupsOf(tiles, links = []) {
     }
     return groups.sort((a, b) => b.length - a.length);
 }
+/** A grid judged against any test of a word: `isWord` answers for a run as spelt, and `readable` says how to name one that is not. `judgeWithWords` is this with a language's list. */
 export function judgeGrid(tiles, isWord, readable = (word) => word, rules = {}) {
     const misspelt = new Set();
     const notWords = [];

package/dist/index.d.ts

@@ -42,3 +42,6 @@ export * from "./computer.types.ts";
 export * from "./computerPlay.ts";
 export * from "./computerTurn.ts";
 export * from "./random.ts";
+export * from "./export.ts";
+export * from "./strings.ts";
+export { KUMIMOJI_VERSION } from "./version.ts";

package/dist/index.js

@@ -42,3 +42,6 @@ export * from "./computer.types.js";
 export * from "./computerPlay.js";
 export * from "./computerTurn.js";
 export * from "./random.js";
+export * from "./export.js";
+export * from "./strings.js";
+export { KUMIMOJI_VERSION } from "./version.js";

package/dist/kumimoji.types.d.ts

@@ -1,6 +1,8 @@
+/** How much of the set a game's bag holds: a short game, half the set, or all of it. */
 export type KumimojiLength = "short" | "medium" | "full";
 /** How many of the bag's tiles are wild: easy the most, hard none (`KUMIMOJI_WILDS`). */
 export type KumimojiLevel = "easy" | "medium" | "hard";
+/** The language of the tiles and of the word list they are judged by. */
 export type KumimojiLanguage = "english" | "japanese";
 /** How far the player has turned the table to look at it: quarter turns clockwise, 0 to 3. The view alone; the grid never turns. */
 export type Turn = 0 | 1 | 2 | 3;

package/dist/partyKept.d.ts

@@ -1,4 +1,5 @@
 import type { PartyGame, PartySettings } from "./party.types.ts";
+/** A table of players as text to keep. `decodeParty` reads it back, and given the word list's `familyKey` checks every tile held against the bag. */
 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;

package/dist/partyKept.js

@@ -18,6 +18,7 @@ import { KUMIMOJI_PARTY, KUMIMOJI_HANDS } from "./tiles.constants.js";
  * nothing to check, and the names in it are the players' own business.
  */
 const VERSION = 1;
+/** A table of players as text to keep. `decodeParty` reads it back, and given the word list's `familyKey` checks every tile held against the bag. */
 export function encodeParty(game) {
     const kept = {
         v: VERSION,

package/dist/partySeats.d.ts

@@ -26,11 +26,13 @@ import type { PartyGame, PartySeat } from "./party.types.ts";
  */
 /** Why nobody can join now, or null when a hand can be dealt. */
 export type JoinRefusal = "over" | "full" | "lastRound" | "bag";
+/** Why nobody can join the table now, or null when a hand can be dealt. */
 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";
+/** Why the player at seat `at` cannot leave now, or null when they can. */
 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;

package/dist/partySeats.js

@@ -2,6 +2,7 @@ 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";
+/** Why nobody can join the table now, or null when a hand can be dealt. */
 export function joinRefused(game) {
     if (game.ending !== null)
         return "over";
@@ -32,6 +33,7 @@ function freePlayerName(players) {
         if (!taken.has(`Player ${number}`))
             return `Player ${number}`;
 }
+/** Why the player at seat `at` cannot leave now, or null when they can. */
 export function leaveRefused(game, at) {
     if (game.ending !== null || game.players[at] === undefined)
         return "over";

package/dist/placement.d.ts

@@ -1,3 +1,4 @@
+/** A square by its row and column. */
 export type Square = {
     row: number;
     col: number;

package/dist/play.d.ts

@@ -59,6 +59,13 @@ export declare function mayTrade(play: TilePlay): boolean;
 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;
+/**
+ * A GAME KEPT half way, as one string (`PuzzleRun.progress`): how many tiles
+ * were taken, the tiles traded back, the hand in its order and the grid
+ * (`encodeGrid`), as `12:q:ae:cat/2o/2w`. The bag is the puzzle's own, from
+ * its seed, so it is not written again, and where on the table the grid stood
+ * is the view's and not kept.
+ */
 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): {

package/dist/play.js

@@ -111,7 +111,7 @@ export function trade(play, handAt) {
 export function isFinished(play, verdict) {
     return play.hand.length === 0 && tilesLeft(play) === 0 && verdict.sound;
 }
-/*
+/**
  * A GAME KEPT half way, as one string (`PuzzleRun.progress`): how many tiles
  * were taken, the tiles traded back, the hand in its order and the grid
  * (`encodeGrid`), as `12:q:ae:cat/2o/2w`. The bag is the puzzle's own, from

package/dist/random.d.ts

@@ -6,6 +6,7 @@
  */
 /** A number in [0, 1), like `Math.random`, from a stream a seed fixes. */
 export type Random = () => number;
+/** A stream of numbers in [0, 1) that the seed fixes: mulberry32. */
 export declare function seededRandom(seed: number): Random;
 /** A copy of the list in a random order (Fisher–Yates). */
 export declare function shuffled<T>(items: readonly T[], random: Random): T[];

package/dist/random.js

@@ -4,6 +4,7 @@
  * is small, fast and good enough for shuffling tiles; nothing here is a
  * credential.
  */
+/** A stream of numbers in [0, 1) that the seed fixes: mulberry32. */
 export function seededRandom(seed) {
     let state = seed >>> 0;
     return () => {

package/dist/react.d.ts

@@ -1,7 +1,9 @@
 import { type HTMLAttributes } from "react";
 import type { GridVerdict, Tiles } from "./grid.ts";
 import { type KumimojiTableOptions } from "./ui/mount.ts";
+/** What `KumimojiBoard` takes: a grid to draw, and any attribute of its `<div>`. */
 export type KumimojiBoardProps = {
+    /** The tiles on the table, by square: `play.tiles`. */
     tiles: Tiles;
     /** From `judgeWithWords`: marks the runs that are not words and the tiles apart. Without it, no marks. */
     verdict?: GridVerdict | null;
@@ -22,6 +24,7 @@ export type KumimojiBoardProps = {
  * with `placeFromHand`, `moveOnTable` and the rest.
  */
 export declare function KumimojiBoard({ tiles, verdict, glyphOf, onSquare, held, square, style, ...element }: KumimojiBoardProps): import("react").JSX.Element;
+/** What `KumimojiTable` takes: the options of `mountKumimoji`, and any attribute of its `<div>`. */
 export type KumimojiTableProps = KumimojiTableOptions & Omit<HTMLAttributes<HTMLDivElement>, keyof KumimojiTableOptions>;
 /**
  * A whole game alone, as a React component: the plain-DOM table
@@ -29,4 +32,4 @@ export type KumimojiTableProps = KumimojiTableOptions & Omit<HTMLAttributes<HTML
  * has it. Options are read when it mounts; give it a new `key` to start over
  * with different ones.
  */
-export declare function KumimojiTable({ language, hand, level, gameLength, diagonals, seed, onFinish, ...element }: KumimojiTableProps): import("react").JSX.Element;
+export declare function KumimojiTable({ language, hand, level, gameLength, diagonals, seed, onFinish, onChange, locale, strings, theme, keep, ...element }: KumimojiTableProps): import("react").JSX.Element;

package/dist/react.js

@@ -34,17 +34,17 @@ export function KumimojiBoard({ tiles, verdict = null, glyphOf, onSquare, held =
  * has it. Options are read when it mounts; give it a new `key` to start over
  * with different ones.
  */
-export function KumimojiTable({ language, hand, level, gameLength, diagonals, seed, onFinish, ...element }) {
+export function KumimojiTable({ language, hand, level, gameLength, diagonals, seed, onFinish, onChange, locale, strings, theme, keep, ...element }) {
     const host = useRef(null);
-    const latest = useRef(onFinish);
+    const latest = useRef({ onFinish, onChange });
     useEffect(() => {
-        latest.current = onFinish;
+        latest.current = { onFinish, onChange };
     });
     useEffect(() => {
         const target = host.current;
         if (target === null)
             return;
-        const table = mountKumimoji(target, { language, hand, level, gameLength, diagonals, seed, onFinish: (result) => latest.current?.(result) });
+        const table = mountKumimoji(target, { language, hand, level, gameLength, diagonals, seed, locale, strings, theme, keep, onFinish: (result) => latest.current.onFinish?.(result), onChange: (saved) => latest.current.onChange?.(saved) });
         return () => table.destroy();
         // Mounted once per key, as documented above.
         // eslint-disable-next-line react-hooks/exhaustive-deps

package/dist/showcase.d.ts

@@ -25,7 +25,9 @@ export type MixShown = {
     /** The tiles with the most, the ones a hand is full of. */
     commonest: string[];
 };
+/** A language's set as a page shows it: every tile with its count, the total, and which are the rarest and the commonest. */
 export declare function mixShown(language: KumimojiLanguage): MixShown;
+/** Every hiragana a tile plays as, itself first: は is は, ば and ぱ. None for a kana that is not a tile's own. */
 export declare function formsOfTile(kana: string): string[];
 /** One length of game at one opening hand: how many tiles it deals from one set and from two, and how many of them are wild at each level. */
 export type LengthRow = {
@@ -35,7 +37,9 @@ export type LengthRow = {
     doubleTiles: number;
     wilds: Record<"easy" | "medium" | "hard", number>;
 };
+/** The lengths of game, shortest first. */
 export declare const LENGTHS: readonly KumimojiLength[];
+/** For one opening hand, each length of game: how many tiles it deals, from one set and from two, and how many are wild at each level. */
 export declare function lengthRows(hand?: number): LengthRow[];
 /**
  * THE TRY-IT ON THE FRONT DOOR: a Kumimoji of ten tiles, played in the

package/dist/showcase.js

@@ -1,6 +1,7 @@
 import { BASE_KANA, CORNER_FORMS, tileKana } from "./kana.js";
 import { kanaTileCode } from "./tileFace.js";
 import { JAPANESE_TILE_MIX, KUMIMOJI_HANDS, TILE_MIX, kumimojiTileCount, kumimojiWildCount } from "./tiles.constants.js";
+/** A language's set as a page shows it: every tile with its count, the total, and which are the rarest and the commonest. */
 export function mixShown(language) {
     const tiles = language === "english"
         ? Object.entries(TILE_MIX).map(([letter, count]) => ({ code: letter, glyph: letter, forms: "", count }))
@@ -17,7 +18,7 @@ export function mixShown(language) {
         commonest: tiles.filter((tile) => tile.count === most).map((tile) => tile.glyph),
     };
 }
-/**
+/*
  * EVERY HIRAGANA A TILE PLAYS AS, itself first: は is は, ば and ぱ; つ is つ,
  * っ and づ; お is お, ぉ and を. Read off the rule the word check uses
  * (`tileKana`) over the whole hiragana block, so the list is what the game
@@ -25,6 +26,7 @@ export function mixShown(language) {
  */
 const HIRAGANA_FIRST = 0x3041;
 const HIRAGANA_LAST = 0x3096;
+/** Every hiragana a tile plays as, itself first: は is は, ば and ぱ. None for a kana that is not a tile's own. */
 export function formsOfTile(kana) {
     if (tileKana(kana) !== kana)
         return [];
@@ -36,7 +38,9 @@ export function formsOfTile(kana) {
     }
     return forms;
 }
+/** The lengths of game, shortest first. */
 export const LENGTHS = ["short", "medium", "full"];
+/** For one opening hand, each length of game: how many tiles it deals, from one set and from two, and how many are wild at each level. */
 export function lengthRows(hand = KUMIMOJI_HANDS.classic) {
     return LENGTHS.map((length) => {
         const tiles = kumimojiTileCount(hand, length);

package/dist/strings.d.ts

@@ -0,0 +1,62 @@
+/**
+ * EVERY WORD KUMIMOJI SHOWS A PERSON, in English and Japanese: the table's
+ * buttons and status lines, and the lines of a game written out as text
+ * (`kumimojiToText`). This is the language of the page, which is not the
+ * language of the tiles: an English page can play kana, and a Japanese page
+ * English letters.
+ *
+ * A page in another language passes its own table, whole or in part:
+ * `{ ...KUMIMOJI_STRINGS.en, draw: "Robar" }`. `{n}`, `{time}` and the other
+ * braces are filled in when a line is shown; a table must keep them.
+ * `docs/strings-ja.md` lists the two languages side by side and is made from
+ * this file.
+ */
+/** The languages the table speaks: English and Japanese. */
+export type KumimojiLocale = "en" | "ja";
+declare const EN: {
+    dealing: string;
+    leftOne: string;
+    left: string;
+    finished: string;
+    tableLabel: string;
+    handLabel: string;
+    emptySquare: string;
+    wildTile: string;
+    wildBlank: string;
+    notWords: string;
+    apart: string;
+    noTiles: string;
+    giveWild: string;
+    changeWild: string;
+    draw: string;
+    trade: string;
+    sort: string;
+    liftAll: string;
+    newGame: string;
+    keep: string;
+    saveJson: string;
+    saveText: string;
+    load: string;
+    loaded: string;
+    loadBad: string;
+    textTitle: string;
+    textEmpty: string;
+    textHand: string;
+    textHandEmpty: string;
+    textLeft: string;
+    textTime: string;
+    textFinished: string;
+    english: string;
+    japanese: string;
+};
+/** Every word the table shows, by name: one table of these for each language. */
+export type KumimojiStrings = {
+    [Name in keyof typeof EN]: string;
+};
+/** The table's words in each language it speaks: `KUMIMOJI_STRINGS.en`, `KUMIMOJI_STRINGS.ja`. */
+export declare const KUMIMOJI_STRINGS: Readonly<Record<KumimojiLocale, KumimojiStrings>>;
+/** A line from a table of strings with its braces filled in: `kumimojiSay(strings.left, { n: 12, time: "1:05" })`. A brace with no value is left as it is. */
+export declare function kumimojiSay(line: string, values?: Readonly<Record<string, string | number>>): string;
+/** The table of strings for a locale with a page's own words laid over it. An unknown locale is English. */
+export declare function kumimojiStrings(locale: KumimojiLocale | string | undefined, own?: Partial<KumimojiStrings>): KumimojiStrings;
+export {};