@johnmorrisdotca/jirai 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,10 +1,26 @@
 # Changelog
 
+All notable changes to this project are written here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-10-05
+
+- The package no longer ships its unit tests (`src/*.test.ts`) in the npm tarball.
+- Each of the demo's settings now has a real line of help under it when the Help switch is on, in English and Japanese.
+- The demo, its README family list and its tests are the family's own: the shared header, footer and list of twenty-two, written from one template.
+- The package check runs on Windows too, where npm is a .cmd file.
+- CI runs on a push to main and on a pull request, not twice per pull request, and the release's notes are the changelog's section.
+- Complete package presentation: desktop and phone screenshots, badges, demo/API links, targeted keywords and linked MIT licence.
+- Source-derived API reference and public API comments, contribution/security files, and a package presentation gate.
+
 ## [0.2.0] - 2026-10-05
 
 - Orthogonal fields: four-neighbour clues, independent hints, proof-backed generation, drawing, saved progress and bilingual controls. Existing square, hexagonal and wraparound modes remain available.
 
-## 0.1.0 — release candidate
+## [0.1.0] - 2026-10-04
 
 - Square, hexagonal and wraparound fields, seeded and configurable.
 - Safe and clear openings, verified no-guess generation and explained deductions.

package/README.md

@@ -1,138 +1,185 @@
-# Jirai 地雷
+<h1 align="center">Jirai <sub>地雷</sub></h1>
 
-**Every number is a clue.** Minesweeper on four-neighbour orthogonal and eight-neighbour square grids, hexagons, or a board whose opposite edges join. Clear the ground, mark the mines, and finish a field made from a seed.
+<p align="center"><strong>Every number is a clue.</strong><br>
+Minesweeper across four-neighbour, eight-neighbour, hexagonal and wraparound grids. Choose a shape, lay a seeded field, and clear it with deductions you can trust.</p>
 
-Plain TypeScript rules, no runtime dependencies. The rules work without a browser; the playable board works in any page. A React wrapper and a custom element are separate imports.
+<p align="center">
+  <a href="https://github.com/johnmorrisdotca/jirai/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/johnmorrisdotca/jirai/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/@johnmorrisdotca/jirai"><img alt="npm" src="https://img.shields.io/npm/v/@johnmorrisdotca/jirai?color=2f5d4a"></a>
+  <a href="./LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-2f5d4a"></a>
+  <img alt="No runtime dependencies" src="https://img.shields.io/badge/runtime%20dependencies-0-2f5d4a">
+  <img alt="TypeScript" src="https://img.shields.io/badge/types-TypeScript-3178c6">
+</p>
 
-## What it does
+<p align="center"><a href="https://johnmorrisdotca.github.io/jirai/"><strong>Play Jirai →</strong></a> · <a href="https://johnmorrisdotca.github.io/jirai/api.html">API reference</a></p>
 
-- Orthogonal four-neighbour, square eight-neighbour, hexagonal and wraparound boards, with width, height and mine count of your own.
-- Rectangle, heart, star and hexagon outlines; wide and tall presets. Cut-outs are outside the playable field.
-- A safe first cell, or a clear opening with all its neighbours safe.
-- Verified no-guess fields. A bounded generator throws `GenerationError` if it cannot prove a board; it never substitutes an ordinary field.
-- Fixed mines after the opening, seeded deals, replayable progress and daily seeds.
-- Flood opening, flags and question marks, chording, explained hints, a clock and a just-the-board dialog.
-- Wood, ivory or slate; flags, stones or flowers. Host CSS may replace the palette.
-- English and Japanese, mouse, touch, long press, and keyboard navigation.
-- Browser generation runs in a module worker, so searching for a no-guess field does not block input.
+<p align="center">
+  <img src="docs/desktop.jpg" alt="Jirai on a desktop: the Minesweeper board and its shape, grid, size, mine-count and material controls in the shared family demo style" width="680">
+  <img src="docs/phone.jpg" alt="Jirai on a phone: a square minefield with touch controls and clear number clues" width="220">
+</p>
 
-## Start a game
+Jirai is a Minesweeper rules engine and player for TypeScript and JavaScript. The core is plain functions; drawing, browser controls, a custom element and an optional React wrapper are separate imports. The package has no runtime dependencies and needs Node 22 or a modern browser.
 
-Once published:
+## In 30 seconds
 
 ```sh
 npm install @johnmorrisdotca/jirai
 ```
 
-The present checkout is a release candidate; its repository URL and package name are intended destinations, not a claim that it has been published.
-
 ```ts
-import { DEFAULT_SETTINGS, newGame, play, visibleGame, hintFor } from "@johnmorrisdotca/jirai";
+import { DEFAULT_SETTINGS, hintFor, newGame, play, visibleGame } from "@johnmorrisdotca/jirai";
 
-let game = newGame({ ...DEFAULT_SETTINGS, width: 16, height: 16, mines: 40, seed: 42 });
-game = play(game, { kind: "reveal", cell: 136 });
-game = play(game, { kind: "mark", cell: 0 });
-const hint = hintFor(visibleGame(game));
+let game = newGame({ ...DEFAULT_SETTINGS, width: 9, height: 9, mines: 10, seed: 42 });
+game = play(game, { kind: "reveal", cell: 40 }); // the first reveal deals the seeded board
+const hint = hintFor(visibleGame(game));          // certain safe cells/mines from clues only
 ```
 
-Every move returns a new game and leaves its input untouched. A move which is unavailable returns the game given. The first reveal deals the board. A mark made before it does not influence the deal.
+For a dedicated four-neighbour variant, its entry fixes the topology for you:
+
+```ts
+import { makeOrthogonalBoard, newOrthogonalGame } from "@johnmorrisdotca/jirai/orthogonal";
+
+const settings = { width: 9, height: 9, mines: 10, noGuess: true, opening: "clear", seed: 42 };
+const game = newOrthogonalGame(settings);
+const board = makeOrthogonalBoard(settings, 40); // counts only edge-sharing neighbours
+```
 
-`Settings.shape` may be `rectangle` (the default), `heart`, `star` or `hexagon`. Shaped fields require at least 9 cells on each side and work on square or hexagonal grids; wraparound requires a rectangle. `activeCells(settings)` returns playable row-major cells and `activeCell(settings, cell)` tests membership. Outside cells have clue −2, never contain mines and are excluded from neighbours, solving, drawing and winning. Mine count must be less than the playable cell count.
+## What it does
 
-The dedicated `@johnmorrisdotca/jirai/orthogonal` entry provides `newOrthogonalGame`, `makeOrthogonalBoard`, `orthogonalNeighbours`, `orthogonalHint`, `encodeOrthogonalGame` and `decodeOrthogonalGame`. It applies four-neighbour rules explicitly, so callers do not need to thread a topology string through setup.
+- **Four rule sets:** square grids count eight neighbours, orthogonal grids count four, hex grids count six axial neighbours, and wraparound grids join opposite square edges.
+- **Board outlines:** rectangles, hearts, stars and hexagon outlines. Shaped boards have cut-outs; wraparound works with rectangles.
+- **A fair first move:** choose a safe first cell or a clear opening with all its neighbours safe.
+- **Verified no-guess deals:** optional deduction-only dealing accepts a board only when the solver proves every safe cell from the opening. It throws `GenerationError` when the bounded search cannot prove one.
+- **Fixed seeded fields:** after the opening, mines never move. A seed and settings reproduce the same deal.
+- **Familiar play:** reveal, flag, question-mark, chord, flood-open, explained hint, timer, undo by saved replay, and a just-the-board dialog.
+- **Accessible controls:** keyboard navigation, pointer and touch, long press to mark, English and Japanese strings, and board labels read by assistive technology.
+- **Materials and markers:** ivory, wood or slate; flags, stones or flowers. Host CSS can replace the palette.
 
-The demo uses the family’s original shared stylesheet and header template, with its five table-cloth choices and bilingual Help controls.
+## Use it in a page
 
-Cells are row-major numbers, zero first: `cell = row * width + column`. Orthogonal clues count only the four edge-sharing cells. Square boards count eight neighbours. Hex boards use axial coordinates: neighbours are left, right, above, above-right, below-left and below. A wrap board joins both opposite edges of a square grid.
+Mount a player into any element. The first reveal asks the module worker to deal the board, so serve the package over HTTP and allow same-origin module workers in your content security policy.
 
 ```ts
-import { mountJirai } from "@johnmorrisdotca/jirai/play";
+import { DEFAULT_SETTINGS, mountJirai } from "@johnmorrisdotca/jirai/play";
 
-const board = mountJirai(document.querySelector<HTMLElement>("#board")!, {
-  settings: { ...DEFAULT_SETTINGS, grid: "hex", seed: 7 },
+const board = mountJirai(document.querySelector<HTMLElement>("#game")!, {
+  settings: { ...DEFAULT_SETTINGS, grid: "orthogonal", seed: 7 },
   material: "wood",
   pieces: "stones",
   language: "en",
-  onChange(game) { /* save gameProgress(game) */ },
-  onFinish(game) { /* game.status is won or lost */ },
-  onError(error) { /* show a generation or worker-loading error */ },
+  onChange(game) { localStorage.setItem("jirai", board.progress()); },
+  onFinish(game) { console.log(game.status, game.helped); },
+  onError(error) { console.error(error); },
 });
-
 board.set({ material: "slate", language: "ja" });
 board.restart();
 board.destroy();
 ```
 
-The handle also offers `game()`, `progress()`, `load(settings, progress?)`, `play(cell, mark?)`, and `hint()`. `controls: false` gives a bare board for a host which supplies its own controls, status and timer. Events `jirai-change` and `jirai-finish` are dispatched on the host.
+The handle also provides `game()`, `progress()`, `play(cell, mark?)`, `hint()`, and `load(settings, progress?)`. Set `controls: false` when your page supplies its own controls and status. Change options with `set`; call `destroy` when the host is removed.
 
-The engine's `Game` contains the answer. Keep that in the process doing the checking. `visibleGame` removes all hidden clues and is the only input the hint solver reads; a player's flags never count as evidence. This is a local puzzle, not a secure multiplayer protocol.
-
-## In a framework
-
-```tsx
-import { JiraiBoard } from "@johnmorrisdotca/jirai/react";
-<JiraiBoard key={seed} settings={{ ...DEFAULT_SETTINGS, seed }} material="wood" />
-```
-
-Options are read when mounted; a new key starts a different board. `onChange`, `onFinish` and `onError` stay current.
-
-Vue, Svelte and Angular can call `mountJirai` on their element in the mount lifecycle and call `destroy` when it leaves. Or use the tag:
+Use the custom element without a mount call:
 
 ```html
 <script type="module">
   import "@johnmorrisdotca/jirai/element/define";
 </script>
-<jirai-board grid="hex" width="9" height="9" mines="10" seed="7"
-  no-guess="true" material="wood" pieces="stones" lang="ja"></jirai-board>
+<jirai-board width="9" height="9" mines="10" seed="42"
+  grid="orthogonal" opening="clear" no-guess="true"
+  material="wood" pieces="stones" lang="ja"></jirai-board>
 ```
 
-Use your bundler or an import map to resolve the package name. The worker is `dist/worker.js`, resolved beside the mounting module; serve the built files over HTTP and allow module workers in your CSP. It is included in the npm tarball. A deployment that rewrites module paths must keep this worker URL working too.
+The optional React entry exports `JiraiBoard` from `@johnmorrisdotca/jirai/react`; React is an optional peer dependency. Its options are read when mounted. Use a new React `key` to start with a different settings object.
 
-## Keep a game
+## Rules and settings
 
-```ts
-import { gameProgress, gameFromProgress, dailySeed } from "@johnmorrisdotca/jirai";
-const saved = gameProgress(game);
-const restored = gameFromProgress(saved); // null for an invalid record
-const seed = dailySeed("2026-10-04", "hex");
-```
+| Setting | Values and limits |
+| --- | --- |
+| `grid` | `square` (eight neighbours), `orthogonal` (four), `hex` (six), or `wrap` (eight; opposite edges join). |
+| `shape` | `rectangle`, `heart`, `star` or `hexagon`; non-rectangles require at least 9 rows and columns. Wraparound requires `rectangle`. |
+| `width`, `height` | 3–60 each, with at most 2,400 total cells. |
+| `mines` | At least one, fewer than active cells, and low enough to leave the selected opening. |
+| `noGuess` | If true, reject any deal the bounded deduction solver cannot finish from the opening. This proves the deal under this solver’s deductions, not a unique solution to every custom board. |
+| `opening` | `safe` protects the first cell; `clear` also protects its neighbours. |
+| `seed` | Integer from 0 through 4,294,967,295. A seed is interpreted together with all other settings and the first cell. |
+| `material`, `pieces`, `language` | `ivory`, `wood`, `slate`; `flags`, `stones`, `flowers`; `en`, `ja`. |
 
-Ordinary grids keep version 1 progress records. Orthogonal records use version 2 and an explicit `variant: "orthogonal"` marker; `decodeOrthogonalGame` accepts only those records. Existing square, hex and wraparound records keep their format and meaning. A seed is only the start of a board's identity: width, height, mine count, grid, no-guess setting, opening policy and first cell matter too. Daily play uses UTC, beginner settings, and the centre opening. The demo's share link includes the first cell after a field has been dealt. Its local save restores the moves, but does not restore elapsed time.
+The built-in presets are beginner (9×9, 10 mines), intermediate (16×16, 40), expert (30×16, 99), wide (21×9, 24), and tall (9×21, 24). They are starting points, not calibrated difficulty ratings.
 
-## The no-guess promise
+## Engine and saved games
 
-The generator deals candidates and plays them using deductions made from visible clues. It uses local counts, differences between contained clue sets, the total mine count, and complete enumeration of small connected frontiers. Enumeration stops at a fixed work budget and discards incomplete results. A candidate is accepted only when all safe cells were reached by proved moves.
+`newGame(settings)` returns an immutable ready game with no dealt mines. `play(game, move)` returns a new state; a move that cannot be made returns the original state. `visibleGame(game)` strips hidden mine locations. `hintFor(visibleGame)` reads only opened clues: flags are marks, never evidence. `makeBoard(settings, first, options?)` deals directly, and `isSolvable(board)` independently checks whether its deduction solver can finish.
 
-This is deliberately conservative. Failing to prove a board does not mean no human could solve it. Very dense custom fields or large expert boards may exceed the search budget. Call `makeBoard(settings, first, { attempts })` to set the candidate budget (1–10000; default 128). Server generation is synchronous; run it in a worker when serving large boards. The mounted browser board already does so.
+`gameProgress(game)` saves the settings and move history, not an unchecked answer. `gameFromProgress(code)` replays and validates the moves, returning `null` for invalid data. The original square, hex and wraparound games use version 1 records. Orthogonal games use version 2 with `variant: "orthogonal"`; `decodeOrthogonalGame` accepts only those records. Keep this distinction when storing old games.
 
-Hints identify a certain safe cell or mine and say which deduction proved it. They do not offer approximate probabilities. Chording still requires correctly placed flags: a matched count of incorrect flags can expose a mine.
+The full engine entry is `@johnmorrisdotca/jirai`; four-neighbour helpers are in `@johnmorrisdotca/jirai/orthogonal`. Drawing is `@johnmorrisdotca/jirai/draw`, browser play is `/play`, and the custom element is `/element` or `/element/define`. The [API guide](docs/API.md) lists the entries and public calls.
 
-## Build and check
+## Drawing and theming
 
-```sh
-pnpm install
-pnpm check
-pnpm test:package
-pnpm exec playwright install chromium
-pnpm test:demo
-pnpm site
-node scripts/serve.mjs
-```
+`boardModel(game, options)` returns row-major labelled cells without touching the DOM. The draw entry exports `JIRAI_STYLE` and the board model. The player uses the same theme variables as its SVG and HTML controls; set `material`, `pieces`, and `language` on mount or override the CSS custom properties in your host.
 
-The generated standalone page is in `docs/`; the preview serves only on `127.0.0.1:6713`. The tests include an exhaustive independent small-board oracle for solver soundness, deterministic dealing, flood/chord rules, immutable moves, replay, and phone/desktop browser flows. The package check installs the actual tarball into an empty temporary project and imports it in Node.
+Materials are `ivory`, `wood` and `slate`. Marker sets are `flags`, `stones` and `flowers`. They change appearance only; the engine still stores covered, flag, question or open states.
 
-## Architecture
+## Limits and browser support
 
-Rules: `jirai.types.ts`, `jirai.constants.ts`, `grid.ts`, `random.ts`, `generate.ts`, `flood.ts`, `game.ts`, `deduce.ts`, `enumerate.ts`, `keep.ts`, `orthogonal.ts`.
+The board is capped at 60 cells per side and 2,400 cells overall. Shapes need at least 9×9; wraparound is rectangular. The no-guess generator tries at most 128 candidates by default. `makeBoard(settings, first, { attempts })` accepts 1–10,000 attempts and can enable or disable local enumeration with `enumerate`; failure raises `GenerationError` rather than silently returning a guessing field. Very dense or shaped boards may exhaust that budget. For synchronous server use, consider running difficult custom settings in a worker.
 
-Drawing and play: `draw.ts`, `style.ts`, `strings.ts`, `mount.ts`, `worker.ts`, `ui.types.ts`. Framework and tag wrappers are separate entries.
+The browser player uses ES modules, SVG, custom elements, dialogs and module workers. Serve built files over HTTP; `file:` pages cannot load its worker. The engine and drawing functions do not need DOM globals. Development and tests require Node 22 or later.
 
-Types and domain constants are kept beside their modules. A new grid is a topology row, not a second copy of the rules. A theme changes drawing, never the answer.
+## The name
 
-## References
+*Jirai* (地雷) is Japanese for a land mine, read じらい, said in three beats, *ji-ra-i*. It is made of 地 (*ji*,
+ground) and 雷 (*rai*, thunder): a mine is thunder buried in the ground. Every number on the board is a clue to
+where it lies. ([Wiktionary: 地雷](https://en.wiktionary.org/wiki/地雷).)
 
-[Simon Tatham's Mines](https://www.chiark.greenend.org.uk/~sgtatham/puzzles/doc/mines.html) is the reference for no-guess play, alternate tilings and wrapping. [David Hill's JSMinesweeper](https://github.com/DavidNHill/JSMinesweeper) is the reference for analysis, opening choices and chording. This implementation does not incorporate their source code.
+## Development
 
-The package follows the pure rules / separate draw / separate play structure of [Suido](https://github.com/johnmorrisdotca/suido), and the optional React wrapper pattern used by Tenka. MIT © John Morris.
+```sh
+pnpm install --frozen-lockfile
+pnpm check          # lint, types and tests
+pnpm test:package   # build and import the actual npm tarball
+pnpm test:demo      # browser flows against the built page
+pnpm site           # build the standalone page into docs/
+```
 
-A run has `helped: true` after a proved hint is shown. This flag survives saved progress and lets a host distinguish assisted finishes. It is client-side state, not a competitive score verification mechanism.
+The standalone game is `docs/index.html`. The preview binds to `127.0.0.1:6713`; see [CONTRIBUTING.md](CONTRIBUTING.md) before changing the engine or player.
+
+## Licence
+
+[MIT](LICENSE) © John Morris. No third-party puzzle boards or artwork are included.
+
+## The family
+
+<!-- family:start (made by scripts/family-readme.mjs from scripts/family-template.mjs; change those, not this) -->
+Jirai is one of twenty-two packages, each made for the same site, each at
+[github.com/johnmorrisdotca](https://github.com/johnmorrisdotca). 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/).
+- [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/).
+- [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/).
+- [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/).
+- [Kazu](https://github.com/johnmorrisdotca/kazu) (数): grid number puzzles: Sudoku and its variants, Futoshiki and Skyscrapers. [Demo](https://johnmorrisdotca.github.io/kazu/).
+- [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/).
+- [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/).
+- [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/).
+
+**This package is Jirai.** The demos of all twenty-two share one header and footer, so each links the rest.
+<!-- family:end -->
+
+## Contributing and security
+
+See [Contributing](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md) and the [Security policy](SECURITY.md).

package/dist/element.d.ts

@@ -2,6 +2,7 @@ declare const ElementBase: {
     new (): HTMLElement;
     prototype: HTMLElement;
 };
+/** Configurable `<jirai-board>` element that owns its mounted game. */
 export declare class JiraiElement extends ElementBase {
     private mounted;
     static observedAttributes: string[];
@@ -10,5 +11,6 @@ export declare class JiraiElement extends ElementBase {
     attributeChangedCallback(): void;
     private mount;
 }
+/** Registers the `<jirai-board>` custom element once in a registry. */
 export declare function defineJirai(registry?: CustomElementRegistry): void;
 export {};

package/dist/element.js

@@ -3,6 +3,7 @@ import { mountJirai } from "./mount.js";
 // Importing this file on a server is harmless; only defineJirai registers the tag.
 const ElementBase = typeof HTMLElement === "undefined" ? class {
 } : HTMLElement;
+/** Configurable `<jirai-board>` element that owns its mounted game. */
 export class JiraiElement extends ElementBase {
     mounted = null;
     static observedAttributes = ["width", "height", "mines", "seed", "grid", "shape", "no-guess", "material", "pieces", "lang"];
@@ -24,5 +25,6 @@ export class JiraiElement extends ElementBase {
         }
     }
 }
+/** Registers the `<jirai-board>` custom element once in a registry. */
 export function defineJirai(registry = customElements) { if (!registry.get("jirai-board"))
     registry.define("jirai-board", JiraiElement); }

package/dist/game.d.ts

@@ -1,8 +1,9 @@
 import type { Board, Game, Move, Settings, VisibleGame } from "./jirai.types.ts";
+/** Creates an unstarted game with covered cells and no dealt answer. */
 export declare function newGame(settings?: Settings): Game;
 /** The clue-only view used by the solver. No hidden mine, including under a flag, survives it. */
 export declare function visibleGame(game: Game): VisibleGame;
-/** Accept a worker's dealt board without changing any moves made before the opening. */
+/** Attaches a worker-dealt board that matches the game's settings, preserving existing moves. */
 export declare function withBoard(game: Game, board: Board): Game;
 /** A legal move returns a new game; an unavailable move returns the same one. */
 export declare function play(game: Game, move: Move): Game;

package/dist/game.js

@@ -3,6 +3,7 @@ import { flood } from "./flood.js";
 import { makeBoard } from "./generate.js";
 import { DEFAULT_SETTINGS, MARKS, MOVES, STATUSES } from "./jirai.constants.js";
 import { neighbours, neighboursOf, validCell, validSettings } from "./grid.js";
+/** Creates an unstarted game with covered cells and no dealt answer. */
 export function newGame(settings = DEFAULT_SETTINGS) {
     if (!validSettings(settings))
         throw new RangeError("Invalid Minesweeper settings.");
@@ -13,7 +14,7 @@ export function visibleGame(game) {
     return { settings: { ...game.settings }, marks: [...game.marks], status: game.status,
         clues: game.marks.map((mark, cell) => !activeCell(game.settings, cell) ? -2 : mark === MARKS.open ? game.board?.clues[cell] ?? null : null) };
 }
-/** Accept a worker's dealt board without changing any moves made before the opening. */
+/** Attaches a worker-dealt board that matches the game's settings, preserving existing moves. */
 export function withBoard(game, board) {
     if (game.board !== null || (game.settings.shape ?? "rectangle") !== (board.settings.shape ?? "rectangle") || Object.keys(DEFAULT_SETTINGS).some(key => game.settings[key] !== board.settings[key]))
         throw new Error("The board does not belong to this game.");

package/dist/grid.d.ts

@@ -1,7 +1,9 @@
 import type { Settings } from "./jirai.types.ts";
 /** Reject a setting before it reaches a board allocation or a shuffle. */
 export declare function validSettings(value: unknown): value is Settings;
+/** Reports whether a row-major cell is inside the board's active shape. */
 export declare function validCell(settings: Settings, cell: number): boolean;
 /** Every neighbour once. Wrap joins both pairs of opposite edges. */
 export declare function neighbours(settings: Settings, cell: number): number[];
+/** Precomputes the neighbour list for each row-major cell. */
 export declare function neighboursOf(settings: Settings): number[][];

package/dist/grid.js

@@ -16,6 +16,7 @@ export function validSettings(value) {
         && (s.opening === "safe" || s.opening === "clear")
         && Number.isInteger(s.seed) && s.seed >= 0 && s.seed <= 0xffffffff;
 }
+/** Reports whether a row-major cell is inside the board's active shape. */
 export function validCell(settings, cell) {
     return Number.isInteger(cell) && cell >= 0 && cell < settings.width * settings.height && activeCell(settings, cell);
 }
@@ -41,6 +42,7 @@ export function neighbours(settings, cell) {
     }
     return [...out].sort((a, b) => a - b);
 }
+/** Precomputes the neighbour list for each row-major cell. */
 export function neighboursOf(settings) {
     return Array.from({ length: settings.width * settings.height }, (_, cell) => neighbours(settings, cell));
 }

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from "./game.ts";
 export * from "./deduce.ts";
 export * from "./keep.ts";
 export { seededRandom } from "./random.ts";
-export declare const VERSION = "0.2.0";
+/** Package version, kept in step with the release metadata. */
+export declare const VERSION = "0.2.1";
 export { SHAPES, activeCell, activeCells } from "./shape.ts";
 export * from "./orthogonal.ts";

package/dist/index.js

@@ -7,6 +7,7 @@ export * from "./game.js";
 export * from "./deduce.js";
 export * from "./keep.js";
 export { seededRandom } from "./random.js";
-export const VERSION = "0.2.0";
+/** Package version, kept in step with the release metadata. */
+export const VERSION = "0.2.1";
 export { SHAPES, activeCell, activeCells } from "./shape.js";
 export * from "./orthogonal.js";

package/dist/jirai.constants.d.ts

@@ -1,32 +1,37 @@
 import type { Grid, Settings } from "./jirai.types.ts";
+/** Names for the supported square, four-neighbour, hex, and wrap grids. */
 export declare const GRIDS: {
     readonly square: "square";
     readonly orthogonal: "orthogonal";
     readonly hex: "hex";
     readonly wrap: "wrap";
 };
+/** Names for the game lifecycle states. */
 export declare const STATUSES: {
     readonly ready: "ready";
     readonly playing: "playing";
     readonly won: "won";
     readonly lost: "lost";
 };
+/** Names for the cell mark cycle. */
 export declare const MARKS: {
     readonly covered: "covered";
     readonly flag: "flag";
     readonly question: "question";
     readonly open: "open";
 };
+/** Names for the moves accepted by the engine. */
 export declare const MOVES: {
     readonly reveal: "reveal";
     readonly mark: "mark";
     readonly chord: "chord";
 };
-/** Hex coordinates are axial: a row is displaced half a cell to the right. */
+/** Neighbour offsets and edge behaviour for each topology. Hex coordinates are axial: each row is displaced half a cell to the right. */
 export declare const GRID_SPECS: Record<Grid, {
     offsets: readonly (readonly [number, number])[];
     wrap: boolean;
 }>;
+/** Common minefield dimensions and mine counts. */
 export declare const PRESETS: {
     readonly beginner: {
         readonly width: 9;
@@ -54,9 +59,15 @@ export declare const PRESETS: {
         readonly mines: 24;
     };
 };
+/** Default beginner game, with a verified no-guess board and clear opening. */
 export declare const DEFAULT_SETTINGS: Settings;
+/** Largest width or height accepted by settings validation. */
 export declare const MAX_SIDE = 60;
+/** Largest total cell count accepted by settings validation. */
 export declare const MAX_CELLS = 2400;
+/** Default candidate-board budget for verified generation. */
 export declare const GENERATION_ATTEMPTS = 128;
+/** Largest frontier enumerated for exact deductions. */
 export declare const ENUMERATION_CELLS = 18;
+/** Maximum partial assignments checked in one exact deduction search. */
 export declare const ENUMERATION_NODES = 100000;

package/dist/jirai.constants.js

@@ -1,14 +1,19 @@
+/** Names for the supported square, four-neighbour, hex, and wrap grids. */
 export const GRIDS = { square: "square", orthogonal: "orthogonal", hex: "hex", wrap: "wrap" };
+/** Names for the game lifecycle states. */
 export const STATUSES = { ready: "ready", playing: "playing", won: "won", lost: "lost" };
+/** Names for the cell mark cycle. */
 export const MARKS = { covered: "covered", flag: "flag", question: "question", open: "open" };
+/** Names for the moves accepted by the engine. */
 export const MOVES = { reveal: "reveal", mark: "mark", chord: "chord" };
-/** Hex coordinates are axial: a row is displaced half a cell to the right. */
+/** Neighbour offsets and edge behaviour for each topology. Hex coordinates are axial: each row is displaced half a cell to the right. */
 export const GRID_SPECS = {
     square: { offsets: [[-1, -1], [0, -1], [1, -1], [-1, 0], [1, 0], [-1, 1], [0, 1], [1, 1]], wrap: false },
     orthogonal: { offsets: [[0, -1], [-1, 0], [1, 0], [0, 1]], wrap: false },
     hex: { offsets: [[-1, 0], [1, 0], [0, -1], [1, -1], [-1, 1], [0, 1]], wrap: false },
     wrap: { offsets: [[-1, -1], [0, -1], [1, -1], [-1, 0], [1, 0], [-1, 1], [0, 1], [1, 1]], wrap: true },
 };
+/** Common minefield dimensions and mine counts. */
 export const PRESETS = {
     beginner: { width: 9, height: 9, mines: 10 },
     intermediate: { width: 16, height: 16, mines: 40 },
@@ -16,9 +21,15 @@ export const PRESETS = {
     wide: { width: 21, height: 9, mines: 24 },
     tall: { width: 9, height: 21, mines: 24 },
 };
+/** Default beginner game, with a verified no-guess board and clear opening. */
 export const DEFAULT_SETTINGS = { ...PRESETS.beginner, grid: GRIDS.square, noGuess: true, opening: "clear", seed: 1 };
+/** Largest width or height accepted by settings validation. */
 export const MAX_SIDE = 60;
+/** Largest total cell count accepted by settings validation. */
 export const MAX_CELLS = 2400;
+/** Default candidate-board budget for verified generation. */
 export const GENERATION_ATTEMPTS = 128;
+/** Largest frontier enumerated for exact deductions. */
 export const ENUMERATION_CELLS = 18;
+/** Maximum partial assignments checked in one exact deduction search. */
 export const ENUMERATION_NODES = 100_000;

package/dist/jirai.types.d.ts

@@ -1,7 +1,10 @@
-/** A cell's number is its row-major place on the board, starting at zero. */
+/** Neighbour topology used to count the clues around each cell. */
 export type Grid = "square" | "orthogonal" | "hex" | "wrap";
+/** Current game state, including whether a mine has been hit. */
 export type Status = "ready" | "playing" | "won" | "lost";
+/** Player-facing state of one cell; the answer is never a mark. */
 export type Mark = "covered" | "flag" | "question" | "open";
+/** Board dimensions and rules used to deal and validate a game. */
 export type Settings = {
     /** Shape omits cells; rectangle is the compatible default. Wrap requires rectangle. */
     shape?: "rectangle" | "heart" | "star" | "hexagon";
@@ -15,10 +18,12 @@ export type Settings = {
     opening: "safe" | "clear";
     seed: number;
 };
+/** A reveal, mark-cycle, or numbered-cell chord applied to a game. */
 export type Move = {
     kind: "reveal" | "mark" | "chord";
     cell: number;
 };
+/** A dealt board including its answer; keep it off public clients. */
 export type Board = {
     settings: Settings;
     mines: readonly boolean[];
@@ -37,6 +42,7 @@ export type Game = {
     /** A proved hint has been shown during this run. */
     helped: boolean;
 };
+/** Answer-free state suitable for deductions, hints, and public display. */
 export type VisibleGame = {
     settings: Settings;
     /** Null is hidden, including flags. Only opened cells give a clue. */
@@ -44,11 +50,13 @@ export type VisibleGame = {
     marks: readonly Mark[];
     status: Status;
 };
+/** An exact count over unknown cells, with the clues that supplied it. */
 export type Constraint = {
     cells: readonly number[];
     mines: number;
     sources: readonly number[];
 };
+/** Certain safe cells and mines proved from visible clues. */
 export type Deduction = {
     safe: readonly number[];
     mines: readonly number[];
@@ -57,10 +65,14 @@ export type Deduction = {
     /** A conflicting clue, or a board with no consistent mine placement. */
     contradiction: boolean;
 };
+/** Work limits for seeded board generation and its no-guess check. */
 export type GenerationOptions = {
     attempts?: number;
     enumerate?: boolean;
 };
+/** Supported interface copy locales. */
 export type Language = "en" | "ja";
+/** Board colours for drawing and mounted play. */
 export type Material = "ivory" | "wood" | "slate";
+/** Symbols used to mark mines. */
 export type Pieces = "flags" | "stones" | "flowers";

package/dist/orthogonal.d.ts

@@ -1,6 +1,7 @@
 import type { Board, GenerationOptions, Game, Settings } from "./jirai.types.ts";
 /** Identifies the four-neighbour rules and progress-code format. */
 export declare const ORTHOGONAL_VARIANT: "orthogonal";
+/** Settings accepted by the four-neighbour-specific helpers. */
 export type OrthogonalSettings = Omit<Settings, "grid">;
 /** Starts a game under four-neighbour rules. */
 export declare function newOrthogonalGame(settings: OrthogonalSettings): Game;

package/dist/react.d.ts

@@ -1,3 +1,3 @@
 import type { JiraiProps } from "./react.types.ts";
-/** The plain-DOM game as a React component. Options are read on mount; give it a new key to load a new board. */
+/** Renders the DOM player inside a React-owned host. Options are read on mount; use a new key to load a new board. */
 export declare function JiraiBoard({ settings, progress, material, pieces, language, controls, onChange, onFinish, onError, ...element }: JiraiProps): import("react").JSX.Element;

package/dist/react.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
 import { mountJirai } from "./mount.js";
-/** The plain-DOM game as a React component. Options are read on mount; give it a new key to load a new board. */
+/** Renders the DOM player inside a React-owned host. Options are read on mount; use a new key to load a new board. */
 export function JiraiBoard({ settings, progress, material, pieces, language, controls, onChange, onFinish, onError, ...element }) {
     const host = useRef(null);
     const latest = useRef({ onChange, onFinish, onError });