@johnmorrisdotca/jirai 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -6,6 +6,29 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-05
+
+Nothing that was exported has changed.
+
+### Added
+
+- A test holds every `@johnmorrisdotca/jirai@N` version pin in the README to this package's major version.
+
+### Changed
+
+- The family's list, in the README and in the demo's footer, names all twenty-four packages, Karakuri and Houseki included.
+- The npm description is one sentence of 250 characters or fewer, so npm and its search show it whole; it is also the repository's About text. `homepage` is the demo site and `author` is `"John Morris"`, the same in every package.
+- The GitHub Actions workflows use the current versions of the actions (checkout 7, setup-node 7, pnpm/action-setup 6; configure-pages 6, upload-pages-artifact 5 and deploy-pages 5 for Pages), which clears GitHub's Node 20 deprecation warning.
+- Every entry has an `import` condition beside `default`.
+- The README has the family's sections in the family's order (Who it is for, Features, Use it in your project, API, Theming, Limits, Browser support, Languages, Roadmap, Architecture, Where it comes from, Changes), the family list sits under "Where it comes from", and a test holds it to them.
+- The development tools are the family's: Vitest 5 and Playwright 1.63, as in the other packages.
+
+## [0.4.0] - 2026-10-05
+
+- **Huge fields.** `hugeSettings(level, { grid, shape, size })` and `HUGE_SIZES` (32×32, 48×24 and 24×48) give each of the four levels on a field of four times the medium level's area, 1,024 to 1,152 squares, with the level's share of mines (a 32×32 has 126, 160, 211 and 256 mines at easy, medium, hard and extra-hard), on every rule set and outline. Every one is dealt and proved to need no guess in a median of 3 to 60 ms (73 ms the slowest of ten 32×32 seeds), on the square, orthogonal, hexagonal and wraparound grids and the heart, star and hexagon outlines, and `src/huge.test.ts` wins a 32×32 at easy and at extra-hard by the explained hints alone. The demo's Level menu offers them (`?level=huge-hard`).
+- **A faster hint.** `deduce` compares a count only with the counts that hold its first square, and `hintFor` builds the neighbours once instead of at every step: on a 32×32 extra-hard field the explained hint took 51 ms on average and up to 400 ms late in the game, now 8 ms and at most 43 ms. The hints it finds are the same ones.
+- Measured, not changed: a reveal or a flag on a 1,024-square board is 4 ms of script, 20 ms with the processor slowed fourfold, and the next frame follows (2,400 squares, the most settings accept: 36 ms), so the board stays plain buttons; the README has the numbers.
+
 ## [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.

package/README.md

@@ -44,7 +44,13 @@ const game = newOrthogonalGame(settings);
 const board = makeOrthogonalBoard(settings, 40); // counts only edge-sharing neighbours
 ```
 
-## What it does
+## Who it is for
+
+- **Puzzle and game sites** that want Minesweeper with boards a player can trust: seeded fields that deal the same everywhere, a safe opening, verified no-guess deals, and the words in English and Japanese.
+- **Developers of other front ends** who want the rules, the dealer and the deduction solver as plain functions, with no DOM, and their own drawing on top.
+- **Players and teachers** who want to learn why a cell is safe: the hints explain the deduction that proves it, and a level steps up a measured difficulty.
+
+## Features
 
 - **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.
@@ -56,7 +62,7 @@ const board = makeOrthogonalBoard(settings, 40); // counts only edge-sharing nei
 - **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.
 
-## Use it in a page
+## Use it in your project
 
 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.
 
@@ -116,6 +122,18 @@ The optional React entry exports `JiraiBoard` from `@johnmorrisdotca/jirai/react
 
 `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).
 
+### Huge fields
+
+`hugeSettings(level, { grid, shape, size })` is the same four levels on a field of four times the area of the medium one: 32×32 (1,024 squares), or 48×24 or 24×48 (1,152; `HUGE_SIZES` lists them) with the level's own share of the mines, so a 32×32 has 126 mines at `easy`, 160 at `medium`, 211 at `hard` and 256 at `extra-hard`, and a heart, star or hexagon outline keeps the share over the squares it has left. They are the same fields as any other: seeded, a safe opening, and every one proved to need no guess, on all four rule sets and all four outlines (`src/huge.test.ts`, and the winning of 32×32 fields at easy and extra-hard by the explained hints alone).
+
+Measured on a Mac (20 cores, busy): dealing and proving a 32×32 takes a median of 3 ms at easy, 5 ms at medium, 11 ms at hard and 60 ms at extra-hard (the slowest of ten seeds 73 ms; 48×24 at extra-hard 54 ms median, 91 ms slowest); the orthogonal four-neighbour field, the hardest to finish, took 46 ms median and 87 ms slowest at 25%. The player deals in a worker, so the page is never held. A reveal or a flag on the 1,024-square board is answered in 4 ms of script on the desk and about 20 ms with the processor slowed fourfold, as a phone's is, and the next frame follows at once (36 ms with 2,400 squares, the most a field may have), so the board is plain buttons still and needs no canvas. The explained `hintFor` takes 8 ms on average and at most 43 ms late in a 32×32 extra-hard field (it was 51 and 400 before 0.4.0).
+
+```ts
+import { DEFAULT_SETTINGS, hugeSettings, newGame } from "@johnmorrisdotca/jirai";
+
+const game = newGame({ ...DEFAULT_SETTINGS, ...hugeSettings("hard"), seed: 7 }); // 32 × 32, 211 mines
+```
+
 ```ts
 import { DEFAULT_SETTINGS, levelSettings, newGame } from "@johnmorrisdotca/jirai";
 
@@ -141,13 +159,17 @@ Orthogonal clues carry less information, so its numbers are smaller at every lev
 
 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
+## API
+
+Every export of every entry point is in the [API reference](https://johnmorrisdotca.github.io/jirai/api.html), made from the source when the demo is built, and the [API guide](docs/API.md) lists the entries and public calls in prose.
+
+## 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.
 
-## Limits and browser support
+## Limits
 
 The board is capped at 60 cells per side and 2,400 cells overall. Shapes need at least 9×9; wraparound is rectangular.
 
@@ -170,34 +192,67 @@ The board is capped at 60 cells per side and 2,400 cells overall. Shapes need at
 
 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.
 
+## Browser support
+
 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.
 
+## Languages
+
+The player's words are English and Japanese, chosen with the `language` option or the `lang` attribute: the buttons, the status lines, the hints and the labels read by assistive technology. Corrections to the Japanese are welcome as issues.
+
+## Roadmap
+
+The engine, the dealer, the hints and the player are in. Nothing else is promised for a date; ideas are welcome in the [issues](https://github.com/johnmorrisdotca/jirai/issues).
+
+## Architecture
+
+```text
+src/
+├── deduce.ts
+├── draw-entry.ts
+├── draw.ts
+├── element-define.ts
+├── element.ts
+├── enumerate.ts
+├── flood.ts
+├── game.ts
+├── generate.ts
+├── grid.ts
+├── index.ts
+├── jirai.constants.ts
+├── jirai.types.ts
+├── keep.ts
+├── levels.ts
+├── measure.ts
+├── mount.ts
+├── orthogonal.ts
+├── play-entry.ts
+├── random.ts
+├── react.tsx
+├── react.types.ts
+├── repair.ts
+├── shape.ts
+├── solve.ts
+├── strings.ts
+├── style.ts
+├── ui.types.ts
+└── worker.ts
+```
+
 ## 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/
-```
-
-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
+## Where it comes from
 
-[MIT](LICENSE) © John Morris. No third-party puzzle boards or artwork are included.
+Minesweeper's rules are common property. Everything here, the rules, the dealer, the solver, the hints, the pictures and the words, is written for the package, and no third-party puzzle boards or artwork are included.
 
-## The family
+### 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
+Jirai 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.
 
 - [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/).
@@ -222,10 +277,32 @@ Jirai is one of twenty-two packages, each made for the same site, each at
 - [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/).
 
-**This package is Jirai.** The demos of all twenty-two share one header and footer, so each links the rest.
+**This package is Jirai.** The demos of all twenty-four share one header and footer, so each links the rest.
 <!-- family:end -->
 
-## Contributing and security
+## Development
+
+```sh
+pnpm install --frozen-lockfile
+pnpm check          # lint, types, tests and the presentation checks
+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/
+```
+
+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.
+
+## Contributing
+
+Bug reports and pull requests are welcome in the [issues](https://github.com/johnmorrisdotca/jirai/issues). See [CONTRIBUTING.md](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md) and the [Security policy](SECURITY.md).
 
-See [Contributing](CONTRIBUTING.md), the [Code of Conduct](CODE_OF_CONDUCT.md) and the [Security policy](SECURITY.md).
+## Changes
+
+Every release is written up in [CHANGELOG.md](./CHANGELOG.md).
+
+## Licence
+
+[MIT](LICENSE) © John Morris. No third-party puzzle boards or artwork are included.

package/dist/deduce.d.ts

@@ -3,6 +3,6 @@ import type { Deduction, VisibleGame } from "./jirai.types.ts";
  * What the clues prove, without reading the answer or trusting a player's
  * flags. A flag is a note; treating it as evidence makes a bad note a bad hint.
  */
-export declare function deduce(game: VisibleGame, knownMines?: ReadonlySet<number>, enumerate?: boolean): Deduction;
+export declare function deduce(game: VisibleGame, knownMines?: ReadonlySet<number>, enumerate?: boolean, adjacent?: readonly (readonly number[])[]): Deduction;
 /** Keep discovering certain mines until there is a safe cell or nothing more is proved. */
 export declare function hintFor(game: VisibleGame): Deduction;

package/dist/deduce.js

@@ -4,8 +4,7 @@ import { neighboursOf } from "./grid.js";
  * What the clues prove, without reading the answer or trusting a player's
  * flags. A flag is a note; treating it as evidence makes a bad note a bad hint.
  */
-export function deduce(game, knownMines = new Set(), enumerate = true) {
-    const adjacent = neighboursOf(game.settings);
+export function deduce(game, knownMines = new Set(), enumerate = true, adjacent = neighboursOf(game.settings)) {
     const constraints = [];
     const empty = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
     for (let cell = 0; cell < game.clues.length; cell += 1) {
@@ -43,10 +42,21 @@ export function deduce(game, knownMines = new Set(), enumerate = true) {
     }
     // Compare a smaller clue with a larger one, including the mine counter.
     // Their difference is another exact count. Never subtract mere overlaps.
-    const sets = [...constraints, total].map((c) => new Set(c.cells));
     const all = [...constraints, total];
-    for (let i = 0; i < all.length; i += 1)
-        for (let j = 0; j < all.length; j += 1) {
+    const sets = all.map((c) => new Set(c.cells));
+    // A constraint can only be inside another that holds its first cell, so each is compared with those alone, in the same order as
+    // comparing it with every other. On a large field that is a handful of neighbours instead of every clue on the board.
+    const holding = new Map();
+    all.forEach((c, index) => { for (const cell of c.cells) {
+        const list = holding.get(cell);
+        if (list === undefined)
+            holding.set(cell, [index]);
+        else
+            list.push(index);
+    } });
+    for (let i = 0; i < all.length; i += 1) {
+        const inside = all[i].cells.length === 0 ? all.map((_, index) => index) : holding.get(all[i].cells[0]);
+        for (const j of inside) {
             if (i === j || all[i].cells.length >= all[j].cells.length)
                 continue;
             if (!all[i].cells.every((cell) => sets[j].has(cell)))
@@ -62,6 +72,7 @@ export function deduce(game, knownMines = new Set(), enumerate = true) {
             if (result !== null)
                 return result;
         }
+    }
     // A whole-board constraint would join otherwise independent components.
     // Local enumeration is conservative; the global counter is used above.
     return enumerate ? enumerateForced(constraints) : empty;
@@ -69,9 +80,10 @@ export function deduce(game, knownMines = new Set(), enumerate = true) {
 /** Keep discovering certain mines until there is a safe cell or nothing more is proved. */
 export function hintFor(game) {
     const known = new Set();
+    const adjacent = neighboursOf(game.settings);
     let last = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
     while (known.size <= game.settings.mines) {
-        const result = deduce(game, known);
+        const result = deduce(game, known, true, adjacent);
         if (result.contradiction || result.safe.length)
             return result;
         const fresh = result.mines.filter((cell) => !known.has(cell));

package/dist/index.d.ts

@@ -8,11 +8,11 @@ export * from "./deduce.ts";
 export * from "./keep.ts";
 export { seededRandom } from "./random.ts";
 /** Package version, kept in step with the release metadata. */
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.4.1";
 export { SHAPES, activeCell, activeCells } from "./shape.ts";
 export * from "./orthogonal.ts";
 export { measureBoard } from "./measure.ts";
 export type { Measure } from "./measure.ts";
 export type { ProofKind, ProofTally } from "./solve.ts";
-export { levelNamed, levelSettings } from "./levels.ts";
-export type { LevelSize } from "./levels.ts";
+export { hugeSettings, levelNamed, levelSettings } from "./levels.ts";
+export type { HugeSize, LevelSize } from "./levels.ts";

package/dist/index.js

@@ -8,8 +8,8 @@ export * from "./deduce.js";
 export * from "./keep.js";
 export { seededRandom } from "./random.js";
 /** Package version, kept in step with the release metadata. */
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.1";
 export { SHAPES, activeCell, activeCells } from "./shape.js";
 export * from "./orthogonal.js";
 export { measureBoard } from "./measure.js";
-export { levelNamed, levelSettings } from "./levels.js";
+export { hugeSettings, levelNamed, levelSettings } from "./levels.js";

package/dist/jirai.constants.d.ts

@@ -45,6 +45,21 @@ export declare const LEVEL_SIZES: Record<(typeof LEVELS)[number], {
     height: number;
     mines: number;
 }>;
+/**
+ * The huge fields: four times the area of a 16×16 (the medium level), 1,024 to 1,152 squares, for a long solve. The same
+ * share of mines as a level, see `hugeSettings`. They are dealt, proved and drawn like any other field: a no-guess deal takes
+ * a few milliseconds to a tenth of a second here, and 2,400 squares is the most `validSettings` accepts.
+ */
+export declare const HUGE_SIZES: readonly [{
+    readonly width: 32;
+    readonly height: 32;
+}, {
+    readonly width: 48;
+    readonly height: 24;
+}, {
+    readonly width: 24;
+    readonly height: 48;
+}];
 /** Common minefield dimensions and mine counts. The levels, their older names, and two shapes of field. */
 export declare const PRESETS: {
     readonly beginner: {

package/dist/jirai.constants.js

@@ -24,6 +24,12 @@ export const LEVEL_SIZES = {
     hard: { width: 30, height: 16, mines: 99 },
     "extra-hard": { width: 40, height: 24, mines: 240 },
 };
+/**
+ * The huge fields: four times the area of a 16×16 (the medium level), 1,024 to 1,152 squares, for a long solve. The same
+ * share of mines as a level, see `hugeSettings`. They are dealt, proved and drawn like any other field: a no-guess deal takes
+ * a few milliseconds to a tenth of a second here, and 2,400 squares is the most `validSettings` accepts.
+ */
+export const HUGE_SIZES = [{ width: 32, height: 32 }, { width: 48, height: 24 }, { width: 24, height: 48 }];
 /** Common minefield dimensions and mine counts. The levels, their older names, and two shapes of field. */
 export const PRESETS = {
     ...LEVEL_SIZES,

package/dist/levels.d.ts

@@ -14,3 +14,19 @@ export declare function levelSettings(level: Level | LevelAlias, board?: {
     grid?: Grid;
     shape?: Settings["shape"];
 }): LevelSize;
+/** The outline of a huge field: one of `HUGE_SIZES`' width and height. */
+export type HugeSize = {
+    width: number;
+    height: number;
+};
+/**
+ * The size and mine count of a level on a huge field: a field of `HUGE_SIZES` (32 × 32 unless `size` says another of them),
+ * with the level's own share of mines over its squares. Easy is 12% mines, medium 16%, hard 21% and extra-hard 25%, as
+ * on the level's own field, and a heart, star or hexagon outline keeps that share over the squares it has left. Every
+ * field is still dealt and proved to need no guess, on every grid. Throws `RangeError` for a name that is no level or a size that is not huge.
+ */
+export declare function hugeSettings(level: Level | LevelAlias, board?: {
+    grid?: Grid;
+    shape?: Settings["shape"];
+    size?: HugeSize;
+}): LevelSize;

package/dist/levels.js

@@ -1,4 +1,4 @@
-import { LEVEL_ALIASES, LEVEL_SIZES, LEVELS } from "./jirai.constants.js";
+import { HUGE_SIZES, LEVEL_ALIASES, LEVEL_SIZES, LEVELS } from "./jirai.constants.js";
 import { activeCells } from "./shape.js";
 /**
  * The level a name means, or null. Accepts `easy`, `medium`, `hard` and `extra-hard` (also written `extra hard`,
@@ -27,3 +27,21 @@ export function levelSettings(level, board = {}) {
     const cells = activeCells(probe).length;
     return { width: size.width, height: size.height, mines: Math.max(1, Math.min(cells - 10, Math.round(size.mines / (size.width * size.height) * cells))) };
 }
+/**
+ * The size and mine count of a level on a huge field: a field of `HUGE_SIZES` (32 × 32 unless `size` says another of them),
+ * with the level's own share of mines over its squares. Easy is 12% mines, medium 16%, hard 21% and extra-hard 25%, as
+ * on the level's own field, and a heart, star or hexagon outline keeps that share over the squares it has left. Every
+ * field is still dealt and proved to need no guess, on every grid. Throws `RangeError` for a name that is no level or a size that is not huge.
+ */
+export function hugeSettings(level, board = {}) {
+    const named = levelNamed(level);
+    if (named === null)
+        throw new RangeError(`Unknown level: ${String(level)}`);
+    const size = board.size ?? HUGE_SIZES[0];
+    if (!HUGE_SIZES.some((huge) => huge.width === size.width && huge.height === size.height))
+        throw new RangeError(`Not a huge size: ${size.width} × ${size.height}`);
+    const own = LEVEL_SIZES[named];
+    const probe = { width: size.width, height: size.height, mines: 1, grid: board.grid ?? "square", shape: board.shape, noGuess: true, opening: "clear", seed: 1 };
+    const cells = activeCells(probe).length;
+    return { width: size.width, height: size.height, mines: Math.max(1, Math.min(cells - 10, Math.round(own.mines / (own.width * own.height) * cells))) };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@johnmorrisdotca/jirai",
-  "version": "0.3.0",
-  "description": "Minesweeper on square, orthogonal, hexagonal and wraparound boards: four levels up to extra-hard, seeded games, a safe opening, verified no-guess boards, explained hints, configurable materials and markers, and a playable board for any page. Zero runtime dependencies.",
+  "version": "0.4.1",
+  "description": "Minesweeper on square, orthogonal, hexagonal and wraparound boards: four levels up to extra-hard, seeded games, a safe opening, verified no-guess boards, explained hints and a playable board for any page. Zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
   "author": "John Morris",
@@ -54,30 +54,37 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
     "./orthogonal": {
       "types": "./dist/orthogonal.d.ts",
+      "import": "./dist/orthogonal.js",
       "default": "./dist/orthogonal.js"
     },
     "./play": {
       "types": "./dist/play-entry.d.ts",
+      "import": "./dist/play-entry.js",
       "default": "./dist/play-entry.js"
     },
     "./draw": {
       "types": "./dist/draw-entry.d.ts",
+      "import": "./dist/draw-entry.js",
       "default": "./dist/draw-entry.js"
     },
     "./element": {
       "types": "./dist/element.d.ts",
+      "import": "./dist/element.js",
       "default": "./dist/element.js"
     },
     "./element/define": {
       "types": "./dist/element-define.d.ts",
+      "import": "./dist/element-define.js",
       "default": "./dist/element-define.js"
     },
     "./react": {
       "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
       "default": "./dist/react.js"
     }
   },
@@ -121,8 +128,8 @@
     "eslint": "^9.0.0",
     "typescript-eslint": "^8.0.0",
     "typescript": "^5.9.0",
-    "vitest": "^4.0.0",
-    "@playwright/test": "^1.58.0",
+    "vitest": "^5.0.0",
+    "@playwright/test": "^1.63.0",
     "@types/react": "^19.0.0",
     "react": "^19.0.0"
   },

package/src/deduce.ts

@@ -6,8 +6,7 @@ import type { Constraint, Deduction, VisibleGame } from "./jirai.types.ts";
  * What the clues prove, without reading the answer or trusting a player's
  * flags. A flag is a note; treating it as evidence makes a bad note a bad hint.
  */
-export function deduce(game: VisibleGame, knownMines: ReadonlySet<number> = new Set(), enumerate = true): Deduction {
-  const adjacent = neighboursOf(game.settings);
+export function deduce(game: VisibleGame, knownMines: ReadonlySet<number> = new Set(), enumerate = true, adjacent: readonly (readonly number[])[] = neighboursOf(game.settings)): Deduction {
   const constraints: Constraint[] = [];
   const empty: Deduction = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
   for (let cell = 0; cell < game.clues.length; cell += 1) {
@@ -31,19 +30,26 @@ export function deduce(game: VisibleGame, knownMines: ReadonlySet<number> = new
   if (unknown.length) { const result = forced(total, "total"); if (result !== null) return result; }
   // Compare a smaller clue with a larger one, including the mine counter.
   // Their difference is another exact count. Never subtract mere overlaps.
-  const sets = [...constraints, total].map((c) => new Set(c.cells));
   const all = [...constraints, total];
-  for (let i = 0; i < all.length; i += 1) for (let j = 0; j < all.length; j += 1) {
-    if (i === j || all[i]!.cells.length >= all[j]!.cells.length) continue;
-    if (!all[i]!.cells.every((cell) => sets[j]!.has(cell))) continue;
-    const c: Constraint = {
-      cells: all[j]!.cells.filter((cell) => !sets[i]!.has(cell)),
-      mines: all[j]!.mines - all[i]!.mines,
-      sources: [...new Set([...all[i]!.sources, ...all[j]!.sources])],
-    };
-    if (c.mines < 0 || c.mines > c.cells.length) return { ...empty, contradiction: true };
-    const result = forced(c, j === all.length - 1 ? "total" : "overlap");
-    if (result !== null) return result;
+  const sets = all.map((c) => new Set(c.cells));
+  // A constraint can only be inside another that holds its first cell, so each is compared with those alone, in the same order as
+  // comparing it with every other. On a large field that is a handful of neighbours instead of every clue on the board.
+  const holding = new Map<number, number[]>();
+  all.forEach((c, index) => { for (const cell of c.cells) { const list = holding.get(cell); if (list === undefined) holding.set(cell, [index]); else list.push(index); } });
+  for (let i = 0; i < all.length; i += 1) {
+    const inside = all[i]!.cells.length === 0 ? all.map((_, index) => index) : holding.get(all[i]!.cells[0]!)!;
+    for (const j of inside) {
+      if (i === j || all[i]!.cells.length >= all[j]!.cells.length) continue;
+      if (!all[i]!.cells.every((cell) => sets[j]!.has(cell))) continue;
+      const c: Constraint = {
+        cells: all[j]!.cells.filter((cell) => !sets[i]!.has(cell)),
+        mines: all[j]!.mines - all[i]!.mines,
+        sources: [...new Set([...all[i]!.sources, ...all[j]!.sources])],
+      };
+      if (c.mines < 0 || c.mines > c.cells.length) return { ...empty, contradiction: true };
+      const result = forced(c, j === all.length - 1 ? "total" : "overlap");
+      if (result !== null) return result;
+    }
   }
   // A whole-board constraint would join otherwise independent components.
   // Local enumeration is conservative; the global counter is used above.
@@ -53,9 +59,10 @@ export function deduce(game: VisibleGame, knownMines: ReadonlySet<number> = new
 /** Keep discovering certain mines until there is a safe cell or nothing more is proved. */
 export function hintFor(game: VisibleGame): Deduction {
   const known = new Set<number>();
+  const adjacent = neighboursOf(game.settings);
   let last: Deduction = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
   while (known.size <= game.settings.mines) {
-    const result = deduce(game, known);
+    const result = deduce(game, known, true, adjacent);
     if (result.contradiction || result.safe.length) return result;
     const fresh = result.mines.filter((cell) => !known.has(cell));
     if (!fresh.length) return last;

package/src/family.test.js

@@ -15,7 +15,9 @@ const id = pkg.name.replace(/^@[^/]+\//, "");
 
 // The recorded hashes. The template's is the one that says every demo's header and footer, and every README's
 // list of the family, are the same text.
-const TEMPLATE = { version: "2026-10-05", sha256: "061b5ed89c345dccb6e029d5091dff0a5bbc4a9b57812fbcd0bd619038bdb7f1" };
+// The template of 2026-10-05 lists twenty-four packages, Karakuri and Houseki included. The family's list is swept again, in every
+// repository at once, when a package is added to it, and this hash is then the new one.
+const TEMPLATE = { version: "2026-10-05", sha256: "a2dc81808be980438bdef8b91f5c0bbff920a739bc50930cd4632cb017c8fa48" };
 const FILES = {
   "scripts/family-readme.mjs": "3c9d5b2cbf17a92d31bced98edac7f544616edb0dff90bf2d141722a9d4516c5",
   "scripts/release-notes.mjs": "efab0fb78ad05973a8885624c0d2ce3b458b55799c11eabaa5176603ce8cd1e9",
@@ -32,7 +34,7 @@ describe("the family template", () => {
   it("lists every package of the family, in order, each with its Japanese name and a line on it", () => {
     expect(FAMILY.map((one) => one.id)).toEqual([
       "korokoro", "kyuubu", "hitotsu", "toranpu", "tane", "narabe", "tenka", "kumimoji", "tsunagi", "jarajara",
-      "suido", "domino", "kotoba", "sugoroku", "kazu", "meikyuu", "hikidashi", "chizu", "bushu", "tobiishi", "jirai", "gunjin",
+      "suido", "domino", "kotoba", "sugoroku", "kazu", "meikyuu", "hikidashi", "chizu", "bushu", "tobiishi", "jirai", "gunjin", "karakuri", "houseki",
     ]);
     for (const one of FAMILY) {
       expect(one.name, one.id).toBe(one.id[0].toUpperCase() + one.id.slice(1));
@@ -75,13 +77,27 @@ describe("the README's family", () => {
   });
 });
 
+describe("the README's version pins", () => {
+  it("name this package's major version, never an older one: a CDN address says @2 once the package is 2.x", () => {
+    const major = pkg.version.split(".")[0];
+    const pins = read("README.md")
+      .split(`${pkg.name}@`)
+      .slice(1)
+      .map((rest) => /^\d+/.exec(rest)?.[0])
+      .filter((pin) => pin !== undefined);
+    for (const pin of pins) expect(pin, `${pkg.name}@${pin} in README.md`).toBe(major);
+  });
+});
+
 describe("the release notes", () => {
   it("are the changelog's section for the version, which the Release workflow puts on the GitHub release", () => {
     const log = "# Changelog\n\n## [Unreleased]\n\n## [1.2.0] - 2026-01-02\n\n### Added\n\n- A thing.\n\n## [1.1.0] - 2026-01-01\n\n- Older.\n\n[Unreleased]: https://example.test\n";
     expect(releaseNotes(log, "1.2.0")).toBe("### Added\n\n- A thing.");
     expect(releaseNotes(log, "1.1.0")).toBe("- Older.");
     expect(releaseNotes(log, "9.9.9")).toBeNull();
-    expect(releaseNotes(read("CHANGELOG.md"), pkg.version)?.length, `CHANGELOG.md has nothing under ## [${pkg.version}]`).toBeGreaterThan(40);
+    // Until a version is published its notes are under [Unreleased]; the release takes the heading with the version and the date.
+    const notes = releaseNotes(read("CHANGELOG.md"), pkg.version) ?? releaseNotes(read("CHANGELOG.md"), "Unreleased");
+    expect(notes?.length, `CHANGELOG.md has nothing under ## [${pkg.version}] or ## [Unreleased]`).toBeGreaterThan(40);
     const workflow = read(".github/workflows/release.yml");
     expect(workflow).toContain("scripts/release-notes.mjs");
     expect(workflow).not.toContain("See CHANGELOG.md.");
@@ -90,7 +106,8 @@ describe("the release notes", () => {
   it("come from a changelog in Keep a Changelog form: an Unreleased heading, then each version in brackets with its date", () => {
     const log = read("CHANGELOG.md");
     expect(log).toContain("\n## [Unreleased]\n");
-    expect(log).toMatch(/^## \[\d+\.\d+\.\d+\] - \d{4}-\d{2}-\d{2}$/m);
+    // Before the first release there is no versioned heading yet, only Unreleased.
+    if (/^## \[\d/m.test(log)) expect(log).toMatch(/^## \[\d+\.\d+\.\d+\] - \d{4}-\d{2}-\d{2}$/m);
     expect(log).not.toMatch(/^## \d/m);
   });
 });

package/src/index.ts

@@ -8,7 +8,7 @@ export * from "./deduce.ts";
 export * from "./keep.ts";
 export { seededRandom } from "./random.ts";
 /** Package version, kept in step with the release metadata. */
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.1";
 
 export { SHAPES, activeCell, activeCells } from "./shape.ts";
 
@@ -16,5 +16,5 @@ export * from "./orthogonal.ts";
 export { measureBoard } from "./measure.ts";
 export type { Measure } from "./measure.ts";
 export type { ProofKind, ProofTally } from "./solve.ts";
-export { levelNamed, levelSettings } from "./levels.ts";
-export type { LevelSize } from "./levels.ts";
+export { hugeSettings, levelNamed, levelSettings } from "./levels.ts";
+export type { HugeSize, LevelSize } from "./levels.ts";

package/src/jirai.constants.ts

@@ -26,6 +26,12 @@ export const LEVEL_SIZES: Record<(typeof LEVELS)[number], { width: number; heigh
   hard: { width: 30, height: 16, mines: 99 },
   "extra-hard": { width: 40, height: 24, mines: 240 },
 };
+/**
+ * The huge fields: four times the area of a 16×16 (the medium level), 1,024 to 1,152 squares, for a long solve. The same
+ * share of mines as a level, see `hugeSettings`. They are dealt, proved and drawn like any other field: a no-guess deal takes
+ * a few milliseconds to a tenth of a second here, and 2,400 squares is the most `validSettings` accepts.
+ */
+export const HUGE_SIZES = [{ width: 32, height: 32 }, { width: 48, height: 24 }, { width: 24, height: 48 }] as const satisfies readonly { width: number; height: number }[];
 /** Common minefield dimensions and mine counts. The levels, their older names, and two shapes of field. */
 export const PRESETS = {
   ...LEVEL_SIZES,

package/src/levels.ts

@@ -1,4 +1,4 @@
-import { LEVEL_ALIASES, LEVEL_SIZES, LEVELS } from "./jirai.constants.ts";
+import { HUGE_SIZES, LEVEL_ALIASES, LEVEL_SIZES, LEVELS } from "./jirai.constants.ts";
 import { activeCells } from "./shape.ts";
 import type { Grid, Level, LevelAlias, Settings } from "./jirai.types.ts";
 
@@ -29,3 +29,23 @@ export function levelSettings(level: Level | LevelAlias, board: { grid?: Grid; s
   const cells = activeCells(probe).length;
   return { width: size.width, height: size.height, mines: Math.max(1, Math.min(cells - 10, Math.round(size.mines / (size.width * size.height) * cells))) };
 }
+
+/** The outline of a huge field: one of `HUGE_SIZES`' width and height. */
+export type HugeSize = { width: number; height: number };
+
+/**
+ * The size and mine count of a level on a huge field: a field of `HUGE_SIZES` (32 × 32 unless `size` says another of them),
+ * with the level's own share of mines over its squares. Easy is 12% mines, medium 16%, hard 21% and extra-hard 25%, as
+ * on the level's own field, and a heart, star or hexagon outline keeps that share over the squares it has left. Every
+ * field is still dealt and proved to need no guess, on every grid. Throws `RangeError` for a name that is no level or a size that is not huge.
+ */
+export function hugeSettings(level: Level | LevelAlias, board: { grid?: Grid; shape?: Settings["shape"]; size?: HugeSize } = {}): LevelSize {
+  const named = levelNamed(level);
+  if (named === null) throw new RangeError(`Unknown level: ${String(level)}`);
+  const size = board.size ?? HUGE_SIZES[0];
+  if (!HUGE_SIZES.some((huge) => huge.width === size.width && huge.height === size.height)) throw new RangeError(`Not a huge size: ${size.width} × ${size.height}`);
+  const own = LEVEL_SIZES[named];
+  const probe = { width: size.width, height: size.height, mines: 1, grid: board.grid ?? "square", shape: board.shape, noGuess: true, opening: "clear", seed: 1 } as const;
+  const cells = activeCells(probe).length;
+  return { width: size.width, height: size.height, mines: Math.max(1, Math.min(cells - 10, Math.round(own.mines / (own.width * own.height) * cells))) };
+}

package/src/readme.test.js

@@ -0,0 +1,34 @@
+// readme.test.js: the README has the sections every package of the family has, in the family's order, each with something in it.
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+const readme = readFileSync("README.md", "utf8").replace(/\r\n/g, "\n");
+const HOUSE = [
+  "In 30 seconds", "Who it is for", "Features", "Use it in your project", "API", "Theming", "Limits", "Browser support",
+  "Languages", "Roadmap", "Architecture", "The name", "Where it comes from", "Development", "Contributing", "Changes", "Licence",
+];
+
+describe("the README's shape", () => {
+  it("has the family's sections, in the family's order, each with something in it", () => {
+    const headings = [...readme.matchAll(/^## (.+)$/gm)].map((match) => match[1]);
+    let from = 0;
+    for (const heading of HOUSE) {
+      const at = headings.indexOf(heading, from);
+      expect(at, `README.md has no "## ${heading}" after the section before it`).toBeGreaterThanOrEqual(from);
+      from = at + 1;
+      const start = readme.indexOf(`\n## ${heading}\n`) + 1;
+      const next = readme.indexOf("\n## ", start + 4);
+      const body = readme.slice(start + heading.length + 4, next < 0 ? undefined : next).trim();
+      expect(body.length, `"## ${heading}" is empty`).toBeGreaterThan(20);
+    }
+  });
+
+  it("puts the family under \"Where it comes from\", one level down", () => {
+    const from = readme.indexOf("\n## Where it comes from\n");
+    const family = readme.indexOf("\n### The family\n");
+    const next = readme.indexOf("\n## Development\n");
+    expect(from).toBeGreaterThan(0);
+    expect(family).toBeGreaterThan(from);
+    expect(family).toBeLessThan(next);
+  });
+});