@johnmorrisdotca/jirai 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,10 +1,34 @@
 # 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.3.0] - 2026-10-05
+
+- An extra-hard level, 40×24 with 240 mines (25%), joins easy, medium and hard on every rule and outline, and every field is still proved to need no guess. `beginner`, `intermediate` and `expert` stay as names for easy, medium and hard, and `PRESETS` keeps them. New: `LEVELS`, `LEVEL_SIZES`, `LEVEL_ALIASES`, `levelNamed`, `levelSettings` (shaped boards keep a level's size and share of mines) and `measureBoard`, which scores density, multi-step share and depth of deduction so the levels can be shown to step up.
+- No-guess dealing is much faster and no longer fails on dense fields: a one-pass solver that agrees with the hint engine replaces the repeated scans (a 30×16 expert square field took over half a second, now about 2 ms), and when no random layout can be finished the closest is repaired by moving single mines next to where the solver stopped. Orthogonal expert fields, which failed five times in six, are now dealt every time. New options `repairs` and `repair: false` (the 0.2 behaviour of giving up after the random layouts).
+- Every field 0.2.1 dealt is dealt again, identically, for the same seed and settings (pinned by tests), and saved games from 0.2.1 replay unchanged. Only settings that used to throw `GenerationError` deal differently, because they now succeed.
+- Narrowed: a cell with no neighbours under the rules (a tip of an orthogonal or hexagonal star) cannot be opened from without a guess, so an opening there now throws `GenerationError` with code `"opening"`, and unreachable cells are made mines. Nothing else is narrowed: extra-hard is offered on square, orthogonal, hexagonal and wraparound grids and on rectangle, heart, star and hexagon outlines.
+- The demo's Size menu is now Level (easy, medium, hard, extra-hard, wide, tall), in English and Japanese, follows the grid and outline, and reads `?level=` (old names too). The Playwright port can be set with `TEST_PORT`.
+
+## [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,231 @@
-# 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.
+- **Four levels:** easy (9×9, 10 mines), medium (16×16, 40), hard (30×16, 99) and extra-hard (40×24, 240), on every rule and outline. The old names `beginner`, `intermediate` and `expert` still work and mean easy, medium and hard.
+- **Verified no-guess deals:** optional deduction-only dealing accepts a board only when the solver proves every safe cell from the opening, even at extra-hard's 25% mines. 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.
+
+## Rules and settings
+
+| 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`. |
 
-## Keep a game
+## Levels
+
+| Level | Size | Mines | Mines per cell | Old name |
+| --- | --- | --- | --- | --- |
+| `easy` | 9×9 | 10 | 12% | `beginner` |
+| `medium` | 16×16 | 40 | 16% | `intermediate` |
+| `hard` | 30×16 | 99 | 21% | `expert` |
+| `extra-hard` | 40×24 | 240 | 25% | |
+
+`levelNamed(name)` returns the level a name means (`extra-hard` may also be written `extra hard`, `extra_hard` or `extraHard`) or `null`. `levelSettings(level, { grid, shape })` returns `{ width, height, mines }`: a rectangle gets the numbers above, and a heart, star or hexagon outline keeps the level's width and height and its share of mines over the cells that are left. `PRESETS` holds the four levels, the three old names, and `wide` (21×9, 24) and `tall` (9×21, 24).
 
 ```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");
+import { DEFAULT_SETTINGS, levelSettings, newGame } from "@johnmorrisdotca/jirai";
+
+const game = newGame({ ...DEFAULT_SETTINGS, ...levelSettings("extra-hard", { grid: "hex", shape: "star" }), grid: "hex", shape: "star", seed: 7 });
 ```
 
-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 levels step up a measured difficulty. `measureBoard(board)` solves a dealt board with the same deductions the hints use and reports its `density`, the share of cells proved by anything beyond one clue's count (`multiStep`), the longest chain of deductions (`depth`), the cells proved by each kind of reasoning, and a `score` (`100 × density + 100 × multiStep + depth ÷ 4`) that puts boards in order. It is not a prediction of how long a person takes. Mean score of 30 seeds, rectangles, opening in the middle:
 
-## The no-guess promise
+| Rule | easy | medium | hard | extra-hard |
+| --- | --- | --- | --- | --- |
+| square (8 neighbours) | 26 | 41 | 63 | 85 |
+| orthogonal (4) | 18 | 26 | 38 | 49 |
+| hexagonal (6) | 21 | 31 | 49 | 65 |
+| wraparound (8) | 25 | 41 | 67 | 96 |
 
-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.
+Orthogonal clues carry less information, so its numbers are smaller at every level; each level is still at least a quarter harder than the one before it on every rule.
 
-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.
+## Engine and saved 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.
+`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. The solver runs the hint engine's deductions to a fixed point in one pass, and is tested to agree with `deduce` on every board.
 
-## Build and check
+`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.
 
-```sh
-pnpm install
-pnpm check
-pnpm test:package
-pnpm exec playwright install chromium
-pnpm test:demo
-pnpm site
-node scripts/serve.mjs
-```
+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.
+
+## Drawing and theming
+
+`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.
+
+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.
 
-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.
+## Limits and browser support
 
-## Architecture
+The board is capped at 60 cells per side and 2,400 cells overall. Shapes need at least 9×9; wraparound is rectangular.
 
-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`.
+**How a no-guess field is dealt.** First the generator draws up to 128 random layouts (`attempts`), exactly as 0.2 did, so every field those versions dealt is dealt again, unchanged, for the same seed. If none of them can be finished by deduction it takes the closest and repairs it: single mines are moved next to the place the solver stopped, a move is kept when it leaves the solver no worse off, and the search starts over from a new layout when it stalls. The work is counted in layouts tried (`repairs`, 12 per cell by default), never in time, so a seed always gives the same field. Every field returned is proved by the same deductions either way; `board.attempt` at or above `attempts` says the field was repaired. `makeBoard(settings, first, { attempts, repairs, repair, enumerate })` accepts 1–10,000 attempts, 0–1,000,000 repairs, `repair: false` for the 0.2 behaviour of giving up after the random layouts, and `enumerate` to switch the exact small-frontier check. Failure raises `GenerationError` rather than returning a guessing field.
 
-Drawing and play: `draw.ts`, `style.ts`, `strings.ts`, `mount.ts`, `worker.ts`, `ui.types.ts`. Framework and tag wrappers are separate entries.
+**Measured generation** (200 seeds for each rule, outline and level, with the opening on a random cell; Node 24 on one core of a shared laptop, so read the milliseconds as an order of magnitude). Every level on every combination dealt a verified field every time, except for the one case below. The slowest single deal in the whole run was 230 ms; the median at extra-hard, the largest and densest level, was 36 ms for a square rectangle (the slowest median), 25 ms orthogonal, 22 ms hexagonal and 3 ms wraparound; its 95th percentile was at most 55 ms. Before 0.3, orthogonal `expert` boards failed five times in six and square ones took over half a second.
 
-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.
+| Level | Median | 95th percentile | Slowest |
+| --- | --- | --- | --- |
+| easy | 0.1–0.5 ms | 0.3–1.1 ms | 3.3 ms |
+| medium | 0.2–1.7 ms | 0.4–3.1 ms | 3.6 ms |
+| hard | 0.6–7.7 ms | 1.2–11.8 ms | 16.7 ms |
+| extra-hard | 3–36 ms | 10–55 ms | 229 ms |
 
-## References
+**What a field cannot do, and what is done about it.**
 
-[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.
+- A cell with no neighbours under the rules (a tip of an orthogonal or hexagonal star) can never be told by a clue. `makeBoard` refuses an opening on one with `GenerationError` code `"opening"` (open another cell), and a field whose opening can reach only part of the outline makes the cut-off cells mines, since nobody has to find a mine to win. This is the only case in which an extra-hard deal fails: 2 of 340 cells on an orthogonal star, 1 on a hexagonal star, 0 on any other outline.
+- Extra-hard is not narrowed for any rule or outline: all of them reach 25% reliably. A custom field much denser than that is still not promised; it raises `GenerationError` when the work budget runs out.
+- The widest fields (30 and 40 columns) scroll sideways inside the board on a narrow screen, as hard always has.
 
-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.
+For synchronous server use, consider running a deal in a worker; a browser deals extra-hard in the board's own worker without a pause.
+
+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.
+
+## The name
+
+*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/地雷).)
+
+## Development
+
+```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/generate.d.ts

@@ -6,5 +6,11 @@ export declare class GenerationError extends Error {
 }
 /** Verify a board from one opening, using only clues that have been uncovered. */
 export declare function isSolvable(board: Board, enumerate?: boolean): boolean;
-/** Deal after the first reveal. A seed fixes the whole candidate stream and the accepted board. */
+/**
+ * Deal after the first reveal. A seed fixes the whole candidate stream and the accepted board.
+ *
+ * A no-guess deal first draws random layouts, as 0.1 and 0.2 did, so every board those versions dealt is still dealt.
+ * If none of them can be finished by deduction it takes the closest and repairs it: single mines are moved near the
+ * place the solver stopped until the solver finishes the whole field. The result is proved the same way either route.
+ */
 export declare function makeBoard(settings: Settings, first: number, options?: GenerationOptions): Board;

package/dist/generate.js

@@ -1,9 +1,9 @@
-import { activeCell, activeCells } from "./shape.js";
-import { deduce } from "./deduce.js";
-import { flood } from "./flood.js";
-import { GENERATION_ATTEMPTS, MARKS, STATUSES } from "./jirai.constants.js";
+import { activeCells } from "./shape.js";
+import { GENERATION_ATTEMPTS } from "./jirai.constants.js";
 import { neighbours, neighboursOf, validCell, validSettings } from "./grid.js";
+import { repair } from "./repair.js";
 import { seededRandom, shuffled } from "./random.js";
+import { Solver } from "./solve.js";
 /** A bounded generator must say it failed, never quietly return a guessing board. */
 export class GenerationError extends Error {
     code;
@@ -15,58 +15,89 @@ export class GenerationError extends Error {
 }
 /** Verify a board from one opening, using only clues that have been uncovered. */
 export function isSolvable(board, enumerate = true) {
-    const adjacent = neighboursOf(board.settings);
-    const open = board.clues.map(() => false);
-    const known = new Set();
-    flood(board.clues, adjacent, open, [board.first]);
-    while (open.filter(Boolean).length < activeCells(board.settings).length - board.settings.mines) {
-        const visible = {
-            settings: board.settings, clues: board.clues.map((n, cell) => activeCell(board.settings, cell) ? open[cell] ? n : null : -2),
-            marks: open.map((yes) => yes ? MARKS.open : MARKS.covered), status: STATUSES.playing,
-        };
-        const result = deduce(visible, known, enumerate);
-        if (result.contradiction)
-            return false;
-        let changed = false;
-        for (const cell of result.mines) {
-            if (!board.mines[cell])
-                return false;
-            if (!known.has(cell)) {
-                known.add(cell);
-                changed = true;
-            }
-        }
-        if (result.safe.some((cell) => board.mines[cell]))
-            return false;
-        if (result.safe.some((cell) => !open[cell])) {
-            flood(board.clues, adjacent, open, result.safe);
-            changed = true;
-        }
-        if (!changed)
-            return false;
-    }
-    return true;
+    const solver = new Solver(board.settings);
+    return solver.run(Int8Array.from(board.clues), board.first, enumerate).solved;
 }
-/** Deal after the first reveal. A seed fixes the whole candidate stream and the accepted board. */
+/** Layouts the repair stage may try, per cell of the field. */
+const REPAIRS_PER_CELL = 12;
+/**
+ * Deal after the first reveal. A seed fixes the whole candidate stream and the accepted board.
+ *
+ * A no-guess deal first draws random layouts, as 0.1 and 0.2 did, so every board those versions dealt is still dealt.
+ * If none of them can be finished by deduction it takes the closest and repairs it: single mines are moved near the
+ * place the solver stopped until the solver finishes the whole field. The result is proved the same way either route.
+ */
 export function makeBoard(settings, first, options = {}) {
     if (!validSettings(settings) || !validCell(settings, first))
         throw new GenerationError("settings", "Invalid board settings or opening cell.");
     const protectedCells = new Set([first, ...(settings.opening === "clear" ? neighbours(settings, first) : [])]);
-    const available = Array.from({ length: settings.width * settings.height }, (_, cell) => cell).filter((cell) => validCell(settings, cell) && !protectedCells.has(cell));
+    const available = activeCells(settings).filter((cell) => !protectedCells.has(cell));
     if (available.length < settings.mines)
         throw new GenerationError("opening", "Too many mines for a safe opening at this cell.");
+    if (settings.noGuess && neighbours(settings, first).length === 0 && available.length > settings.mines)
+        throw new GenerationError("opening", "The opening cell touches no other cell, so no clue can follow from it. Open another cell.");
     const attempts = options.attempts ?? GENERATION_ATTEMPTS;
     if (!Number.isInteger(attempts) || attempts < 1 || attempts > 10_000)
         throw new GenerationError("settings", "Attempts must be between 1 and 10000.");
+    const repairs = options.repairs ?? (options.repair === false ? 0 : REPAIRS_PER_CELL * settings.width * settings.height);
+    if (!Number.isInteger(repairs) || repairs < 0 || repairs > 1_000_000)
+        throw new GenerationError("settings", "Repairs must be between 0 and 1000000.");
+    const enumerate = options.enumerate ?? true;
     const random = seededRandom(settings.seed);
     const adjacent = neighboursOf(settings);
+    const solver = new Solver(settings, adjacent);
+    const cells = settings.width * settings.height;
+    const layout = new Uint8Array(cells), clues = new Int8Array(cells);
+    let best = null, fewest = Infinity;
+    const board = (attempt) => ({
+        settings: { ...settings }, mines: Array.from(layout, Boolean), clues: Array.from(clues), first, attempt,
+    });
     for (let attempt = 0; attempt < (settings.noGuess ? attempts : 1); attempt += 1) {
-        const places = new Set(shuffled(available, random).slice(0, settings.mines));
-        const mines = available.length ? Array.from({ length: settings.width * settings.height }, (_, cell) => places.has(cell)) : [];
-        const clues = mines.map((mine, cell) => !activeCell(settings, cell) ? -2 : mine ? -1 : adjacent[cell].filter((n) => mines[n]).length);
-        const board = { settings: { ...settings }, mines, clues, first, attempt };
-        if (!settings.noGuess || isSolvable(board, options.enumerate ?? true))
-            return board;
+        layout.fill(0);
+        for (const cell of shuffled(available, random).slice(0, settings.mines))
+            layout[cell] = 1;
+        solver.clueFor(layout, clues);
+        if (!settings.noGuess)
+            return board(attempt);
+        const report = solver.run(clues, first, enumerate);
+        if (report.solved)
+            return board(attempt);
+        if (report.remaining < fewest) {
+            fewest = report.remaining;
+            best = layout.slice();
+        }
+    }
+    if (best !== null && repairs > 0) {
+        // A cell no chain of neighbours reaches from the opening can never be told by a clue. Make each a mine and leave it
+        // be: nobody has to find a mine to win, and nobody could find that one. Fewer mines than such cells: do not try.
+        const reached = new Set([first]);
+        for (const cell of reached)
+            for (const n of adjacent[cell])
+                reached.add(n);
+        const stranded = available.filter((cell) => !reached.has(cell));
+        if (stranded.length <= settings.mines) {
+            const reachable = available.filter((cell) => reached.has(cell));
+            const place = () => {
+                layout.fill(0);
+                for (const cell of stranded)
+                    layout[cell] = 1;
+                for (const cell of shuffled(reachable, random).slice(0, settings.mines - stranded.length))
+                    layout[cell] = 1;
+                solver.clueFor(layout, clues);
+            };
+            // Begin from the closest of the random layouts, with the stranded cells made mines at the cost of other mines.
+            layout.set(best);
+            const movable = reachable.filter((cell) => layout[cell]);
+            for (const cell of shuffled(stranded.filter((c) => !layout[c]), random)) {
+                const from = movable.pop();
+                layout[from] = 0;
+                layout[cell] = 1;
+            }
+            solver.clueFor(layout, clues);
+            const outcome = repair(solver, layout, clues, first, new Set([...protectedCells, ...stranded]), random, repairs, enumerate, place);
+            if (outcome.solved)
+                return board(attempts + outcome.tries);
+        }
     }
     throw new GenerationError("exhausted", "No verified board found within the work budget. Try another seed, fewer mines, or a different opening.");
 }

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[][];