@johnmorrisdotca/kumimoji 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,25 @@ All notable changes to this project are written down here. The format follows
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-10-14
+
+The table is a custom element with the family's standard embed attributes and a shared builder, and the package has an English and Japanese documentation site with a checked example for every export. The rules, generation, seeds and saved games are unchanged.
+
+### Added
+
+- Add the bilingual documentation site, checked public examples, paired guides, local search and machine-readable pages.
+- Add the shared crossword-table builder and validated iframe route with reflected settings and display options. Preserve native saved/table access and gameplay methods; presentation updates now retain play.
+- Add native ready/set, optional initial saved state, control visibility and localized load failures, forwarded by the React wrapper. Preserve event shapes with composed JSON-safe snapshots and add load/error events.
+- Share a package-independent embed builder for option controls, preview adapters, code tabs and shareable links.
+
+### Changed
+
+- Synchronize documentation tooling for repository layouts, generated type references, Node entry points and repository-specific README links.
+- Keep large documentation resource catalogues on the entry index and the active resource beside core navigation, preserving every reference page; render valid default imports in HTML and Markdown.
+- The props table of `KumimojiBoard` moved from the README to `docs/react.md`, so that the README, which now lists the sports packages too, stays under npm's 65,536 characters; the README keeps a summary and a link.
+- Group the package family by kind, alphabetize each group, and include the geography packages and REST in Pieces in the shared footer and README.
+- Update the shared family description for addresses in all seven supported countries, including France and Germany.
+
 ## [1.2.2] - 2026-10-06
 
 Nothing that was exported has changed.
@@ -157,7 +176,8 @@ The first release.
   `@johnmorrisdotca/kumimoji/react`.
 - A static demo for GitHub Pages.
 
-[Unreleased]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.2.1...HEAD
+[Unreleased]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.2.2...v1.3.0
 [1.2.1]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.2.0...v1.2.1
 [1.1.1]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/johnmorrisdotca/kumimoji/releases/tag/v1.1.0

package/README.md

@@ -1,4 +1,4 @@
-<h1 align="center">Kumimoji <sub>組み文字</sub></h1>
+<h1 align="center">Kumimoji <sub>組み文字</sub> — Crossword tile game in English and Japanese</h1>
 
 <p align="center"><strong>The crossword tile race: a word game where you build one crossword from a bag of letter tiles.</strong><br>
 In English and in Japanese kana. The rules as pure, seeded TypeScript, two word lists, a computer player, and a table to play on in React, Vue, Svelte, Angular or plain HTML.</p>
@@ -10,9 +10,11 @@ In English and in Japanese kana. The rules as pure, seeded TypeScript, two word
   <a href="./NOTICE.md"><img alt="Japanese word list: CC BY-SA 4.0" src="https://img.shields.io/badge/Japanese%20words-CC%20BY--SA%204.0-b5452c"></a>
   <img alt="No dependencies" src="https://img.shields.io/badge/dependencies-0-2f5d4a">
   <img alt="TypeScript" src="https://img.shields.io/badge/types-TypeScript-3178c6">
+  <a href="https://johnmorrisdotca.github.io/kumimoji/docs/api/main/index.html"><img alt="679.1 kB minified and gzipped" src="https://img.shields.io/badge/min%2Bgzip-679.1%20kB-2f5d4a"></a>
+  <a href="https://www.npmjs.com/package/@johnmorrisdotca/kumimoji#provenance"><img alt="Published with npm provenance" src="https://img.shields.io/badge/npm-provenance-2f5d4a"></a>
 </p>
 
-<p align="center"><a href="https://johnmorrisdotca.github.io/kumimoji/"><strong>Play a game →</strong></a> · <a href="https://johnmorrisdotca.github.io/kumimoji/api.html">API reference</a> · <a href="docs/API.md">The API in full</a></p>
+<p align="center"><a href="https://johnmorrisdotca.github.io/kumimoji/"><strong>Play a game →</strong></a> · <a href="https://johnmorrisdotca.github.io/kumimoji/docs/">Documentation</a> · <a href="https://johnmorrisdotca.github.io/kumimoji/docs/guides/getting-started.html">Getting started</a> · <a href="https://johnmorrisdotca.github.io/kumimoji/api.html">API reference</a> · <a href="docs/API.md">The API in full</a></p>
 
 <table align="center">
 <tr>
@@ -184,6 +186,19 @@ Each picture is the table the package draws, taken from [the demo](https://johnm
 
 ## Use it in your project
 
+### Install under another name
+
+```sh
+npm install word-game@npm:@johnmorrisdotca/kumimoji
+```
+
+```ts no-check
+import "word-game/words";
+import { loadTileWords, generateKumimoji } from "word-game";
+await loadTileWords("english");
+console.log(generateKumimoji(7,"easy",42).seed);
+```
+
 ### Install
 
 ```sh
@@ -384,6 +399,12 @@ fetches when a game is first dealt.
 
 The cookbook, with the output of each example, is under [Examples](#examples).
 
+### Embed builder and reflected settings
+
+[Build a crossword-table embed](https://johnmorrisdotca.github.io/kumimoji/builder.html), preview English letters or Japanese kana and copy element, iframe, module, React 19, Vue, Svelte, Angular, HTML or URL code. It saves no play automatically. The builder/frame defaults `keep` off; the existing element default remains on for compatibility.
+
+Every attribute reflects to a property. New `daily` accepts today or an explicit UTC date (the `seed="daily"` alias remains); `controls`, device/light/dark `theme`, `size` (small 320px, medium 480px, large 640px), pixel `width` and spoken `label` are available. `table`, `saved`, `newGame()` and `setGame()` remain. `options` accepts every native table choice, including initial saved state and callbacks. Readiness is available as `table.ready`; `table.set(...)` updates presentation without redealing. Load errors are visible and reported through `onError`/`kumimoji-error`. `defineTable` accepts a custom tag and is server-safe. See [the embed guide](docs/embeds.md).
+
 ## Examples
 
 Every TypeScript and JavaScript block that can run is type-checked against the built package and run by `pnpm test:readme`, so the output after `// →` is what the code prints. The word lists are read from the package's files in Node, so nothing here uses a network.
@@ -747,7 +768,7 @@ The JSON, as `kumimojiToJSON` writes it:
 {
   "format": 1,
   "game": "kumimoji",
-  "generator": "kumimoji 1.2.2",
+  "generator": "kumimoji 1.3.0",
   "size": 3,
   "level": "hard",
   "seed": 44,
@@ -843,7 +864,7 @@ turn tiles into words: `glyphOf`, `soundOf`, `wordOf`, `wildFor`, `isWild`,
 
 ## API
 
-The [API reference](https://johnmorrisdotca.github.io/kumimoji/api.html) lists every export of every entry point with its signature and its doc comment. It is made from the source by `pnpm site`, so it cannot fall behind the code.
+The [documentation](https://johnmorrisdotca.github.io/kumimoji/docs/) includes bilingual guides, local search, signatures, parameters, return values and checked examples, built from source by `pnpm docs:site`. The [API index](https://johnmorrisdotca.github.io/kumimoji/api.html) preserves export anchors.
 
 Every function, type and constant has a doc comment, so an editor shows this
 as you type. The entries:
@@ -885,7 +906,7 @@ The types are `TilePlay`, `Tiles`, `GridVerdict`, `GridRules`, `Run`,
 
 ### The table
 
-`mountKumimoji(element, options?)` from `@johnmorrisdotca/kumimoji/ui` deals and plays a whole game alone in the element and returns a handle (`play()`, `saved()`, `newGame(options?)`, `setGame(saved)`, `setLocale(locale, strings?)`, `destroy()`). Its options are `language`, `hand`, `level`, `gameLength`, `diagonals`, `seed`, `onFinish`, `onChange`, `locale`, `strings`, `theme` and `keep`; each, with its default, is in [docs/API.md](docs/API.md#the-table).
+`mountKumimoji(element, options?)` from `@johnmorrisdotca/kumimoji/ui` deals and plays a whole game alone in the element and returns a handle (`play()`, `saved()`, `newGame(options?)`, `setGame(saved)`, `setLocale(locale, strings?)`, `ready`, `set(options)`, `destroy()`). Its options are `language`, `hand`, `level`, `gameLength`, `diagonals`, `seed`, `onFinish`, `onChange`, `locale`, `strings`, `theme`, `keep`, `controls`, `saved` and `onError`; each, with its default, is in [docs/API.md](docs/API.md#the-table).
 
 ### The element
 
@@ -914,19 +935,7 @@ export function Board() {
 }
 ```
 
-| `KumimojiBoard` prop | What it does |
-| --- | --- |
-| `tiles` | The tiles on the table: `play.tiles` |
-| `verdict` | From `judgeWithWords`: rings the runs that are not words and fades the tiles apart |
-| `glyphOf` | What to print on a tile: `words.glyphOf` for the language played |
-| `onSquare` | Called with a square's key when it is pressed, empty or not |
-| `held` | A square to ring, such as the one holding a tile picked up |
-| `square` | The side of a square in pixels; 36 by default |
-| anything else | Passed to the `<div>` |
-
-`KumimojiTable` takes every option of `mountKumimoji` as a prop, and anything
-else for its `<div>`. Options are read when it mounts; give it a new `key` to
-start over with different ones.
+The props of `KumimojiBoard` (`tiles`, `verdict`, `glyphOf`, `onSquare`, `held`, `square`, and anything else for its `<div>`) and of `KumimojiTable` are in [docs/react.md](docs/react.md).
 
 ## Theming
 
@@ -1104,35 +1113,67 @@ issue and we will add you.
 ### The family
 
 <!-- family:start (made by scripts/family-readme.mjs from scripts/family-template.mjs; change those, not this) -->
-Kumimoji is one of twenty-four packages, each made for the same site, each at
-[github.com/johnmorrisdotca](https://github.com/johnmorrisdotca). The code of every one is MIT.
+Kumimoji is one of thirty-two packages, each made for the same site, each at
+[github.com/johnmorrisdotca](https://github.com/johnmorrisdotca) or [github.com/spxis](https://github.com/spxis). The code of every one is MIT.
 
-- [Korokoro](https://github.com/johnmorrisdotca/korokoro) (コロコロ): dice, with notation, exact odds, real sounds and the dice of many games. [Demo](https://johnmorrisdotca.github.io/korokoro/).
-- [Kyuubu](https://github.com/johnmorrisdotca/kyuubu) (キューブ): a turning cube for the browser, 2×2 to 7×7, with record solves to replay. [Demo](https://johnmorrisdotca.github.io/kyuubu/).
-- [Hitotsu](https://github.com/johnmorrisdotca/hitotsu) (一つ): a colour-card shedding game for two to eight, with the house rules people play. [Demo](https://johnmorrisdotca.github.io/hitotsu/).
-- [Toranpu](https://github.com/johnmorrisdotca/toranpu) (トランプ): a deck of playing cards, card games with computer players, and solitaires. [Demo](https://johnmorrisdotca.github.io/toranpu/).
-- [Tane](https://github.com/johnmorrisdotca/tane) (種): seeded random numbers and daily seeds, the same in every browser and on every server. [Demo](https://johnmorrisdotca.github.io/tane/).
+**Games — board**
+
+- [Domino](https://github.com/johnmorrisdotca/domino) (ドミノ): dominoes and Mexican Train. [Demo](https://johnmorrisdotca.github.io/domino/).
+- [Gunjin](https://github.com/johnmorrisdotca/gunjin) (軍人): five hidden-rank strategy games with pass-the-device play. [Demo](https://johnmorrisdotca.github.io/gunjin/).
 - [Narabe](https://github.com/johnmorrisdotca/narabe) (並べ): one rules engine for abstract board games, from gomoku and Reversi to Go and checkers. [Demo](https://johnmorrisdotca.github.io/narabe/).
+- [Sugoroku](https://github.com/johnmorrisdotca/sugoroku) (双六): backgammon and its variants, with the doubling cube and match play. [Demo](https://johnmorrisdotca.github.io/sugoroku/).
 - [Tenka](https://github.com/johnmorrisdotca/tenka) (天下): world conquest for two to six, on a map of the real world. [Demo](https://johnmorrisdotca.github.io/tenka/).
-- [Kumimoji](https://github.com/johnmorrisdotca/kumimoji) (組み文字): a crossword tile race, in English and Japanese kana. [Demo](https://johnmorrisdotca.github.io/kumimoji/).
-- [Tsunagi](https://github.com/johnmorrisdotca/tsunagi) (繋ぎ): a line-joining logic puzzle whose every level has exactly one answer. [Demo](https://johnmorrisdotca.github.io/tsunagi/).
+
+**Games — cards & tiles**
+
+- [Hitotsu](https://github.com/johnmorrisdotca/hitotsu) (一つ): a colour-card shedding game for two to eight, with the house rules people play. [Demo](https://johnmorrisdotca.github.io/hitotsu/).
 - [Jarajara](https://github.com/johnmorrisdotca/jarajara) (ジャラジャラ): mahjong tiles drawn as SVG, stacked layouts, and the matching solitaire Awase. [Demo](https://johnmorrisdotca.github.io/jarajara/).
-- [Suido](https://github.com/johnmorrisdotca/suido) (水道): a pipe puzzle: turn the pieces until the water reaches every drain. [Demo](https://johnmorrisdotca.github.io/suido/).
-- [Domino](https://github.com/johnmorrisdotca/domino) (ドミノ): dominoes and Mexican Train. [Demo](https://johnmorrisdotca.github.io/domino/).
-- [Kotoba](https://github.com/johnmorrisdotca/kotoba) (言葉): word lists and word-game rules in English, French, German and Japanese. [Demo](https://johnmorrisdotca.github.io/kotoba/).
-- [Sugoroku](https://github.com/johnmorrisdotca/sugoroku) (双六): backgammon and its variants, with the doubling cube and match play. [Demo](https://johnmorrisdotca.github.io/sugoroku/).
+- [Kumimoji](https://github.com/johnmorrisdotca/kumimoji) (組み文字): a crossword tile race, in English and Japanese kana. [Demo](https://johnmorrisdotca.github.io/kumimoji/).
+- [Toranpu](https://github.com/johnmorrisdotca/toranpu) (トランプ): a deck of playing cards, card games with computer players, and solitaires. [Demo](https://johnmorrisdotca.github.io/toranpu/).
+
+**Games — puzzles**
+
+- [Houseki](https://github.com/johnmorrisdotca/houseki) (宝石): gem and stone matching puzzles: falling triplets, stone collapse, colour chains and gem swap. [Demo](https://johnmorrisdotca.github.io/houseki/).
+- [Jirai](https://github.com/johnmorrisdotca/jirai) (地雷): minesweeper on shaped grids with verified no-guess boards. [Demo](https://johnmorrisdotca.github.io/jirai/).
+- [Karakuri](https://github.com/johnmorrisdotca/karakuri) (からくり): eight hyper-casual puzzle games, some of them physics: draw a shield, pull pins, cut ropes, slide blocks, pour tubes. [Demo](https://johnmorrisdotca.github.io/karakuri/).
 - [Kazu](https://github.com/johnmorrisdotca/kazu) (数): grid number puzzles: Sudoku and its variants, Futoshiki and Skyscrapers. [Demo](https://johnmorrisdotca.github.io/kazu/).
+- [Kyuubu](https://github.com/johnmorrisdotca/kyuubu) (キューブ): a turning cube for the browser, 2×2 to 7×7, with record solves to replay. [Demo](https://johnmorrisdotca.github.io/kyuubu/).
 - [Meikyuu](https://github.com/johnmorrisdotca/meikyuu) (迷宮): mazes on squares, hexagons, triangles and circles, made from a seed and drawn through with a finger or the mouse. [Demo](https://johnmorrisdotca.github.io/meikyuu/).
+- [Suido](https://github.com/johnmorrisdotca/suido) (水道): a pipe puzzle: turn the pieces until the water reaches every drain. [Demo](https://johnmorrisdotca.github.io/suido/).
+- [Tobiishi](https://github.com/johnmorrisdotca/tobiishi) (飛び石): peg solitaire with nine boards and seeded solvable challenges. [Demo](https://johnmorrisdotca.github.io/tobiishi/).
+- [Tsunagi](https://github.com/johnmorrisdotca/tsunagi) (繋ぎ): a line-joining logic puzzle whose every level has exactly one answer. [Demo](https://johnmorrisdotca.github.io/tsunagi/).
+
+**Games — dice & random**
+
+- [Korokoro](https://github.com/johnmorrisdotca/korokoro) (コロコロ): dice, with notation, exact odds, real sounds and the dice of many games. [Demo](https://johnmorrisdotca.github.io/korokoro/).
+- [Tane](https://github.com/johnmorrisdotca/tane) (種): seeded random numbers and daily seeds, the same in every browser and on every server. [Demo](https://johnmorrisdotca.github.io/tane/).
+
+**Language**
+
+- [Bushu](https://github.com/johnmorrisdotca/bushu) (部首): find a kanji by the parts it is made of. [Demo](https://johnmorrisdotca.github.io/bushu/).
 - [Hikidashi](https://github.com/johnmorrisdotca/hikidashi) (引き出し): a drawer of small Japanese text tools: era dates, kanji numerals, readings and sentence difficulty. [Demo](https://johnmorrisdotca.github.io/hikidashi/).
+- [Kotoba](https://github.com/johnmorrisdotca/kotoba) (言葉): word lists and word-game rules in English, French, German and Japanese. [Demo](https://johnmorrisdotca.github.io/kotoba/).
+
+**Geography & data**
+
+- [address-plus](https://github.com/johnmorrisdotca/address-plus) (アドレスプラス): parse and format addresses in the United States, Canada, Japan, Australia, France, Germany and the United Kingdom. [Demo](https://johnmorrisdotca.github.io/address-plus/).
 - [Chizu](https://github.com/johnmorrisdotca/chizu) (地図): maps of the world and of countries' regions, in English and Japanese, with a quiz and callouts. [Demo](https://johnmorrisdotca.github.io/chizu/).
-- [Bushu](https://github.com/johnmorrisdotca/bushu) (部首): find a kanji by the parts it is made of. [Demo](https://johnmorrisdotca.github.io/bushu/).
-- [Tobiishi](https://github.com/johnmorrisdotca/tobiishi) (飛び石): peg solitaire with nine boards and seeded solvable challenges. [Demo](https://johnmorrisdotca.github.io/tobiishi/).
-- [Jirai](https://github.com/johnmorrisdotca/jirai) (地雷): minesweeper on shaped grids with verified no-guess boards. [Demo](https://johnmorrisdotca.github.io/jirai/).
-- [Gunjin](https://github.com/johnmorrisdotca/gunjin) (軍人): five hidden-rank strategy games with pass-the-device play. [Demo](https://johnmorrisdotca.github.io/gunjin/).
-- [Karakuri](https://github.com/johnmorrisdotca/karakuri) (からくり): eight hyper-casual puzzle games, some of them physics: draw a shield, pull pins, cut ropes, slide blocks, pour tubes. [Demo](https://johnmorrisdotca.github.io/karakuri/).
-- [Houseki](https://github.com/johnmorrisdotca/houseki) (宝石): gem and stone matching puzzles: falling triplets, stone collapse, colour chains and gem swap. [Demo](https://johnmorrisdotca.github.io/houseki/).
+- [Hata](https://github.com/johnmorrisdotca/hata) (旗): country and regional flags as SVG, at their true proportions and keyed by ISO code. [Demo](https://johnmorrisdotca.github.io/hata/).
+- [Kuni](https://github.com/johnmorrisdotca/kuni) (国): countries and their regions, with ISO codes and names in English and Japanese. [Demo](https://johnmorrisdotca.github.io/kuni/).
+
+**Sports**
+
+- [Dougu Sports](https://github.com/johnmorrisdotca/dougu-sports) (道具): sports emblems as SVG: trophies, medals, crests, and the ball and gear of every sport, with optional 3D turning. [Demo](https://johnmorrisdotca.github.io/dougu-sports/).
+- [Kyogijo Stadiums](https://github.com/johnmorrisdotca/kyogijo-stadiums) (競技場): sports fields, rinks, courts and ballparks drawn to scale as SVG, with each team and the score on them. [Demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/).
+- [Senshu Jerseys](https://github.com/johnmorrisdotca/senshu-jerseys) (選手): sports jerseys, sweaters, kits, caps, helmets and retired-number banners as SVG, front and back, with optional 2.5D turning. [Demo](https://johnmorrisdotca.github.io/senshu-jerseys/).
+- [Taisen Brackets](https://github.com/johnmorrisdotca/taisen-brackets) (対戦): a sport-agnostic tournament bracket, drawn as SVG, from a list of ties. [Demo](https://johnmorrisdotca.github.io/taisen-brackets/).
+
+**Developer tools**
+
+- [REST in Pieces](https://github.com/spxis/rest-in-pieces) (レスト・イン・ピーシーズ): seeded test data and REST APIs for frontend development, with latency and error drills. [Demo](https://spxis.github.io/rest-in-pieces/).
+
 
-**This package is Kumimoji.** The demos of all twenty-four share one header and footer, so each links the rest.
+**This package is Kumimoji.** The demos of all thirty-two share one header and footer, so each links the rest.
 <!-- family:end -->
 
 ## Development
@@ -1160,7 +1201,7 @@ Please follow the [code of conduct](./CODE_OF_CONDUCT.md). A way to make a check
 
 See [CHANGELOG.md](./CHANGELOG.md).
 
-The latest release is 1.2.2: the README takes the family's full layout, with pictures of the table and examples that are run.
+The latest release is 1.3.0: the table's standard embed attributes, the shared embed builder, and the documentation site with a checked example for every export.
 
 ## Licence
 

package/dist/check.d.ts

@@ -11,9 +11,34 @@ import type { KumimojiCheck, KumimojiLevel, KumimojiOptions } from "./kumimoji.t
  * Written out here rather than asked of the play page, which is what made the
  * grid; the list must have been loaded (`loadTileWords`), and a check that
  * cannot read it refuses.
+ *
+ * @param size - The supported initial hand size.
+ * @param givens - The original bag of internal tile codes.
+ * @param answer - The encoded completed grid to verify.
+ * @param options - Native game, component or presentation options.
+ * @returns WHETHER A GRID FINISHES A KUMIMOJI: the one check the server also runs. O(squares) and a lookup a word, nothing searched: the grid uses exactly the tiles of the bag, as many of each, it is all one piece, and every run of two or more across or down is in the list — and, for a game set up with Diagonals, every run of three or more along a diagonal. Which tiles were traded on the way does not matter — a finished game holds the whole bag whatever came out of it when — so the answer is the grid alone.
+ * @example
+ * ```ts
+ * import { checkKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(checkKumimoji(3,"cat","cat",{level:"hard"}));
+ * ```
  */
 export declare function checkKumimoji(size: number, givens: string, answer: string, options?: KumimojiOptions & {
     level?: KumimojiLevel;
 }): KumimojiCheck;
-/** A finished game's leaderboard points (`KUMIMOJI_SCORE`): ten a tile, and up to as much again for speed. */
+/** A finished game's leaderboard points (`KUMIMOJI_SCORE`): ten a tile, and up to as much again for speed.
+ *
+ * @param givens - The original bag of internal tile codes.
+ * @param elapsedMs - The elapsed solve time in milliseconds.
+ * @returns A finished game's leaderboard points (`KUMIMOJI_SCORE`): ten a tile, and up to as much again for speed.
+ * @example
+ * ```ts
+ * import { kumimojiPoints } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiPoints("cat",12000));
+ * ```
+ */
 export declare function kumimojiPoints(givens: string, elapsedMs: number): number;

package/dist/check.js

@@ -14,6 +14,20 @@ import { tileWords } from "./tileWords.js";
  * Written out here rather than asked of the play page, which is what made the
  * grid; the list must have been loaded (`loadTileWords`), and a check that
  * cannot read it refuses.
+ *
+ * @param size - The supported initial hand size.
+ * @param givens - The original bag of internal tile codes.
+ * @param answer - The encoded completed grid to verify.
+ * @param options - Native game, component or presentation options.
+ * @returns WHETHER A GRID FINISHES A KUMIMOJI: the one check the server also runs. O(squares) and a lookup a word, nothing searched: the grid uses exactly the tiles of the bag, as many of each, it is all one piece, and every run of two or more across or down is in the list — and, for a game set up with Diagonals, every run of three or more along a diagonal. Which tiles were traded on the way does not matter — a finished game holds the whole bag whatever came out of it when — so the answer is the grid alone.
+ * @example
+ * ```ts
+ * import { checkKumimoji } from "@johnmorrisdotca/kumimoji";
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ *
+ * await loadTileWordsFromModule("english");
+ * console.log(checkKumimoji(3,"cat","cat",{level:"hard"}));
+ * ```
  */
 export function checkKumimoji(size, givens, answer, options = {}) {
     const gameLength = options.gameLength ?? "short";
@@ -60,7 +74,18 @@ export function checkKumimoji(size, givens, answer, options = {}) {
         return { ok: false, reason: "the grid is not finished" };
     return { ok: true };
 }
-/** A finished game's leaderboard points (`KUMIMOJI_SCORE`): ten a tile, and up to as much again for speed. */
+/** A finished game's leaderboard points (`KUMIMOJI_SCORE`): ten a tile, and up to as much again for speed.
+ *
+ * @param givens - The original bag of internal tile codes.
+ * @param elapsedMs - The elapsed solve time in milliseconds.
+ * @returns A finished game's leaderboard points (`KUMIMOJI_SCORE`): ten a tile, and up to as much again for speed.
+ * @example
+ * ```ts
+ * import { kumimojiPoints } from "@johnmorrisdotca/kumimoji";
+ *
+ * console.log(kumimojiPoints("cat",12000));
+ * ```
+ */
 export function kumimojiPoints(givens, elapsedMs) {
     const tiles = givens.length;
     const base = KUMIMOJI_SCORE.tile * tiles;

package/dist/computer.types.d.ts

@@ -1,5 +1,14 @@
 import type { PartyGame } from "./party.types.ts";
-/** What a computer did in one step of its turn, for the line over its table. */
+/** What a computer did in one step of its turn, for the line over its table.
+ *
+ * @example
+ * ```ts
+ * import type { ComputerSaid } from "@johnmorrisdotca/kumimoji";
+ *
+ * const value: ComputerSaid = {kind:"drew"};
+ * console.log(value);
+ * ```
+ */
 export type ComputerSaid = {
     kind: "rebuilt";
 } | {
@@ -16,7 +25,20 @@ export type ComputerSaid = {
 } | {
     kind: "resigned";
 };
-/** One step of a computer's turn: the game after it, and what it did. The last step's game is the one kept. */
+/** One step of a computer's turn: the game after it, and what it did. The last step's game is the one kept.
+ *
+ * @example
+ * ```ts
+ * import { startParty } from "@johnmorrisdotca/kumimoji";
+ * import type { ComputerStep } from "@johnmorrisdotca/kumimoji";
+ *
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * const value: ComputerStep = {game,said:{kind:"drew"}};
+ * console.log(value);
+ * ```
+ */
 export type ComputerStep = {
     game: PartyGame;
     said: ComputerSaid;

package/dist/computerPlay.d.ts

@@ -1,17 +1,60 @@
 import { type GridRules, type GridVerdict, type Tiles } from "./grid.ts";
 import { type TilePlay } from "./play.ts";
 import type { TileWords } from "./tileWords.ts";
-/** Whether a grid is sound, read against the loaded word list by the game's rules: the same judgement the desk shows. */
+/** Whether a grid is sound, read against the loaded word list by the game's rules: the same judgement the desk shows.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param words - The loaded native language word list and tile mappings.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns Whether a grid is sound, read against the loaded word list by the game's rules: the same judgement the desk shows.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { judgeTiles } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(judgeTiles(tiles,words));
+ * ```
+ */
 export declare function judgeTiles(tiles: Tiles, words: TileWords, rules?: GridRules): GridVerdict;
 /**
  * THE COMPUTER'S NEXT WORD: its play after laying the best word its hand can
  * lay on its table, and the word, or null when there is none. The grid after
  * it is judged against the list, by the game's rules (`rules`), and is
  * always sound.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param words - The loaded native language word list and tile mappings.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns THE COMPUTER'S NEXT WORD: its play after laying the best word its hand can lay on its table, and the word, or null when there is none. The grid after it is judged against the list, by the game's rules (`rules`), and is always sound.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { bestLaying, deal } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * console.log(bestLaying(play,words)?.word);
+ * ```
  */
 export declare function bestLaying(play: TilePlay, words: TileWords, rules?: GridRules): {
     play: TilePlay;
     word: string;
 } | null;
-/** The tile a computer trades: its rarest letter in the set, the first of those in its hand; never a wild. Null for a hand of wilds. */
+/** The tile a computer trades: its rarest letter in the set, the first of those in its hand; never a wild. Null for a hand of wilds.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns The tile a computer trades: its rarest letter in the set, the first of those in its hand; never a wild. null for a hand of wilds.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { deal, tradeChoice } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * console.log(tradeChoice(play.hand,words));
+ * ```
+ */
 export declare function tradeChoice(hand: readonly string[], words: TileWords): number | null;

package/dist/computerPlay.js

@@ -28,7 +28,22 @@ function plainOf(tile, words) {
     const sound = words.soundOf(tile);
     return sound === null ? "" : (words.codeOf(sound) ?? "");
 }
-/** Whether a grid is sound, read against the loaded word list by the game's rules: the same judgement the desk shows. */
+/** Whether a grid is sound, read against the loaded word list by the game's rules: the same judgement the desk shows.
+ *
+ * @param tiles - The map from row,column square names to internal tile codes.
+ * @param words - The loaded native language word list and tile mappings.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns Whether a grid is sound, read against the loaded word list by the game's rules: the same judgement the desk shows.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { judgeTiles } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const tiles = new Map([["0,0","c"],["0,1","a"],["0,2","t"]]);
+ * console.log(judgeTiles(tiles,words));
+ * ```
+ */
 export function judgeTiles(tiles, words, rules = {}) {
     return judgeWithWords(tiles, words, rules);
 }
@@ -173,6 +188,20 @@ const JUDGED_MOST = 12;
  * lay on its table, and the word, or null when there is none. The grid after
  * it is judged against the list, by the game's rules (`rules`), and is
  * always sound.
+ *
+ * @param play - The current immutable solo-game progress.
+ * @param words - The loaded native language word list and tile mappings.
+ * @param rules - Whether diagonal runs are also judged.
+ * @returns THE COMPUTER'S NEXT WORD: its play after laying the best word its hand can lay on its table, and the word, or null when there is none. The grid after it is judged against the list, by the game's rules (`rules`), and is always sound.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { bestLaying, deal } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * console.log(bestLaying(play,words)?.word);
+ * ```
  */
 export function bestLaying(play, words, rules = {}) {
     if (play.hand.length === 0)
@@ -186,7 +215,21 @@ export function bestLaying(play, words, rules = {}) {
     }
     return null;
 }
-/** The tile a computer trades: its rarest letter in the set, the first of those in its hand; never a wild. Null for a hand of wilds. */
+/** The tile a computer trades: its rarest letter in the set, the first of those in its hand; never a wild. Null for a hand of wilds.
+ *
+ * @param hand - The hand size or tile codes, as declared by the function signature.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns The tile a computer trades: its rarest letter in the set, the first of those in its hand; never a wild. null for a hand of wilds.
+ * @example
+ * ```ts
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { deal, tradeChoice } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const play = deal("catdog",3);
+ * console.log(tradeChoice(play.hand,words));
+ * ```
+ */
 export function tradeChoice(hand, words) {
     let chosen = null;
     let fewest = Infinity;

package/dist/computerTurn.d.ts

@@ -24,9 +24,48 @@ import type { TileWords } from "./tileWords.ts";
  * - Resign only where the rules offer it (`mayResign`) and it can do nothing
  *   at all: nothing to lay, nothing to trade for, and it is not its last turn.
  */
-/** The most things a computer does in one turn before pressing Done: at the page's pause, a turn of about three seconds. */
+/** The most things a computer does in one turn before pressing Done: at the page's pause, a turn of about three seconds.
+ *
+ * @example
+ * ```ts
+ * import { COMPUTER_STEPS_MOST } from "@johnmorrisdotca/kumimoji";
+ * console.log(COMPUTER_STEPS_MOST);
+ * ```
+ */
 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. */
+/** 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.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns 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.
+ * @example
+ * ```ts no-run
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { planComputerTurn, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(planComputerTurn(game,words).map(step=>step.said));
+ * ```
+ */
 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. */
+/** 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.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns 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.
+ * @example
+ * ```ts no-run
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { afterComputerTurn, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(afterComputerTurn(game,words).turn);
+ * ```
+ */
 export declare function afterComputerTurn(game: PartyGame, words: TileWords): PartyGame;

package/dist/computerTurn.js

@@ -25,11 +25,34 @@ import { liftAll, mayTrade, trade } from "./play.js";
  * - Resign only where the rules offer it (`mayResign`) and it can do nothing
  *   at all: nothing to lay, nothing to trade for, and it is not its last turn.
  */
-/** The most things a computer does in one turn before pressing Done: at the page's pause, a turn of about three seconds. */
+/** The most things a computer does in one turn before pressing Done: at the page's pause, a turn of about three seconds.
+ *
+ * @example
+ * ```ts
+ * import { COMPUTER_STEPS_MOST } from "@johnmorrisdotca/kumimoji";
+ * console.log(COMPUTER_STEPS_MOST);
+ * ```
+ */
 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. */
+/** 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.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns 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.
+ * @example
+ * ```ts no-run
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { planComputerTurn, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(planComputerTurn(game,words).map(step=>step.said));
+ * ```
+ */
 export function planComputerTurn(game, words) {
     const steps = [];
     if (game.ending !== null || !isComputer(game, game.turn))
@@ -89,7 +112,23 @@ export function planComputerTurn(game, words) {
     take(endTurn(now, verdict(), handSpells), { kind: "done", out: goesOut(now, verdict()) });
     return steps;
 }
-/** 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. */
+/** 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.
+ *
+ * @param game - The current immutable shared-bag party game.
+ * @param words - The loaded native language word list and tile mappings.
+ * @returns 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.
+ * @example
+ * ```ts no-run
+ * import { loadTileWordsFromModule } from "@johnmorrisdotca/kumimoji/words";
+ * import { afterComputerTurn, startParty } from "@johnmorrisdotca/kumimoji";
+ *
+ * const words = await loadTileWordsFromModule("english");
+ * const settings = {size:3,level:"hard",seed:44,gameLength:"short",language:"english",doubleSet:false,diagonals:false,hints:false} as const;
+ * const bag = "catdogsun";
+ * const game = startParty(settings,bag,["Seat 1","Seat 2"]);
+ * console.log(afterComputerTurn(game,words).turn);
+ * ```
+ */
 export function afterComputerTurn(game, words) {
     return planComputerTurn(game, words).at(-1)?.game ?? game;
 }