@johnmorrisdotca/jirai 0.2.0 → 0.3.0

package/dist/solve.js

@@ -0,0 +1,336 @@
+import { enumerateForced } from "./enumerate.js";
+import { neighboursOf } from "./grid.js";
+import { activeCell } from "./shape.js";
+const COVERED = 0, OPEN = 1, MINE = 2, OUTSIDE = 3;
+/**
+ * The same deductions as `deduce` (one clue, two overlapping clues, the mine counter, exact enumeration of a
+ * small frontier), run to a fixed point over one board in a single pass instead of one deduction per scan of the
+ * whole field. A deduction found here is a deduction `deduce` would find; the order differs, the closure does not.
+ * Built once for a set of settings, then `run` as often as needed on different mine layouts.
+ */
+export class Solver {
+    settings;
+    adjacent;
+    cells;
+    safeTotal;
+    mineTotal;
+    state;
+    start;
+    need;
+    unknown;
+    chain;
+    dirty;
+    searched;
+    marks;
+    seen;
+    visit;
+    queue = [];
+    stack = [];
+    clues = new Int8Array(0);
+    stamp = 0;
+    covered = 0;
+    left = 0;
+    opened = 0;
+    free = 0;
+    deepestMine = 0;
+    depth = 0;
+    broken = false;
+    searching = true;
+    proved = { count: 0, overlap: 0, total: 0, enumeration: 0 };
+    constructor(settings, adjacent = neighboursOf(settings)) {
+        this.settings = settings;
+        this.adjacent = adjacent;
+        this.cells = settings.width * settings.height;
+        this.start = Uint8Array.from({ length: this.cells }, (_, cell) => activeCell(settings, cell) ? COVERED : OUTSIDE);
+        this.safeTotal = this.start.reduce((sum, state) => sum + (state === COVERED ? 1 : 0), 0) - settings.mines;
+        this.mineTotal = settings.mines;
+        this.state = new Uint8Array(this.cells);
+        this.need = new Int8Array(this.cells);
+        this.unknown = new Int8Array(this.cells);
+        this.chain = new Int16Array(this.cells);
+        this.dirty = new Uint8Array(this.cells);
+        this.searched = new Uint8Array(this.cells);
+        this.marks = new Int32Array(this.cells);
+        this.seen = new Int32Array(this.cells);
+        this.visit = new Int32Array(this.cells);
+    }
+    /** Clues of a layout: -1 for a mine, -2 outside the shape, otherwise the count of neighbouring mines. */
+    clueFor(mines, into = new Int8Array(this.cells)) {
+        for (let cell = 0; cell < this.cells; cell += 1) {
+            if (this.start[cell] === OUTSIDE) {
+                into[cell] = -2;
+                continue;
+            }
+            if (mines[cell]) {
+                into[cell] = -1;
+                continue;
+            }
+            let count = 0;
+            for (const n of this.adjacent[cell])
+                if (mines[n])
+                    count += 1;
+            into[cell] = count;
+        }
+        return into;
+    }
+    /** Play the opening at `first` and every deduction after it. `clues` is read, never changed. */
+    run(clues, first, enumerate = true) {
+        this.clues = clues;
+        this.state.set(this.start);
+        this.need.fill(0);
+        this.unknown.fill(0);
+        this.chain.fill(0);
+        this.dirty.fill(0);
+        this.searched.fill(0);
+        this.queue.length = 0;
+        this.covered = this.safeTotal + this.mineTotal;
+        this.left = this.mineTotal;
+        this.opened = 0;
+        this.free = 0;
+        this.deepestMine = 0;
+        this.depth = 0;
+        this.broken = false;
+        this.proved = { count: 0, overlap: 0, total: 0, enumeration: 0 };
+        if ((clues[first] ?? -1) < 0)
+            return this.report();
+        this.reveal(first, 0, null);
+        this.free = this.opened;
+        for (;;) {
+            while (this.queue.length > 0 && !this.broken) {
+                const cell = this.queue.pop();
+                this.dirty[cell] = 0;
+                while (this.step(cell)) { /* a clue may settle more than once */ }
+            }
+            if (this.broken || this.opened === this.safeTotal || this.covered === 0)
+                break;
+            if (this.counter())
+                continue;
+            if (enumerate && this.enumerate())
+                continue;
+            break;
+        }
+        return this.report();
+    }
+    report() {
+        const solved = !this.broken && this.opened === this.safeTotal;
+        return { solved, remaining: this.safeTotal - this.opened, unresolved: this.covered, opened: this.opened, free: this.free, proved: { ...this.proved }, depth: this.depth };
+    }
+    touch(cell) {
+        this.searched[cell] = 0;
+        if (!this.dirty[cell]) {
+            this.dirty[cell] = 1;
+            this.queue.push(cell);
+        }
+    }
+    /** Open a cell known to be safe, and flood through every zero. `kind` null is the free opening. */
+    reveal(start, depth, kind) {
+        const stack = this.stack;
+        stack.length = 0;
+        stack.push(start);
+        let first = true;
+        while (stack.length > 0) {
+            const cell = stack.pop();
+            if (this.state[cell] !== COVERED)
+                continue;
+            if (this.clues[cell] < 0) {
+                this.broken = true;
+                return;
+            }
+            if (first && kind !== null) {
+                this.proved[kind] += 1;
+                if (depth > this.depth)
+                    this.depth = depth;
+            }
+            first = false;
+            this.state[cell] = OPEN;
+            this.covered -= 1;
+            this.opened += 1;
+            let mines = 0, unknown = 0;
+            for (const n of this.adjacent[cell]) {
+                const s = this.state[n];
+                if (s === MINE)
+                    mines += 1;
+                else if (s === COVERED)
+                    unknown += 1;
+                else if (s === OPEN) {
+                    this.unknown[n] -= 1;
+                    if (depth > this.chain[n])
+                        this.chain[n] = depth;
+                    this.touch(n);
+                }
+            }
+            this.need[cell] = this.clues[cell] - mines;
+            this.unknown[cell] = unknown;
+            this.chain[cell] = depth;
+            if (this.clues[cell] === 0) {
+                for (const n of this.adjacent[cell])
+                    if (this.state[n] === COVERED)
+                        stack.push(n);
+            }
+            else if (unknown > 0)
+                this.touch(cell);
+        }
+    }
+    flag(cell, depth, kind) {
+        if (this.state[cell] !== COVERED)
+            return;
+        if (this.clues[cell] >= 0) {
+            this.broken = true;
+            return;
+        }
+        this.state[cell] = MINE;
+        this.covered -= 1;
+        this.left -= 1;
+        this.proved[kind] += 1;
+        if (depth > this.depth)
+            this.depth = depth;
+        if (depth > this.deepestMine)
+            this.deepestMine = depth;
+        for (const n of this.adjacent[cell])
+            if (this.state[n] === OPEN) {
+                this.unknown[n] -= 1;
+                this.need[n] -= 1;
+                if (depth > this.chain[n])
+                    this.chain[n] = depth;
+                this.touch(n);
+            }
+    }
+    settle(cells, safe, depth, kind) {
+        for (const cell of cells) {
+            if (safe)
+                this.reveal(cell, depth, kind);
+            else
+                this.flag(cell, depth, kind);
+        }
+    }
+    /** One deduction from the clue at `cell` alone, or from it and an overlapping clue. */
+    step(cell) {
+        if (this.broken || this.state[cell] !== OPEN || this.unknown[cell] === 0)
+            return false;
+        const around = this.adjacent[cell];
+        const unknown = this.unknown[cell], need = this.need[cell];
+        if (need < 0 || need > unknown) {
+            this.broken = true;
+            return false;
+        }
+        const depth = this.chain[cell] + 1;
+        if (need === 0 || need === unknown) {
+            this.settle(around.filter((n) => this.state[n] === COVERED), need === 0, depth, "count");
+            return true;
+        }
+        const mine = ++this.stamp;
+        for (const n of around)
+            if (this.state[n] === COVERED)
+                this.marks[n] = mine;
+        const compared = ++this.stamp;
+        for (const x of around) {
+            if (this.state[x] !== COVERED)
+                continue;
+            for (const other of this.adjacent[x]) {
+                if (other === cell || this.state[other] !== OPEN || this.unknown[other] === 0 || this.seen[other] === compared)
+                    continue;
+                this.seen[other] = compared;
+                let common = 0;
+                for (const y of this.adjacent[other])
+                    if (this.state[y] === COVERED && this.marks[y] === mine)
+                        common += 1;
+                const there = this.unknown[other];
+                let rest, mines;
+                if (common === there && there < unknown) {
+                    rest = around.filter((n) => this.state[n] === COVERED && !this.adjacent[other].includes(n));
+                    mines = need - this.need[other];
+                }
+                else if (common === unknown && unknown < there) {
+                    rest = this.adjacent[other].filter((n) => this.state[n] === COVERED && this.marks[n] !== mine);
+                    mines = this.need[other] - need;
+                }
+                else
+                    continue;
+                if (mines < 0 || mines > rest.length) {
+                    this.broken = true;
+                    return false;
+                }
+                if (mines !== 0 && mines !== rest.length)
+                    continue;
+                this.settle(rest, mines === 0, 1 + Math.max(depth - 1, this.chain[other]), "overlap");
+                return true;
+            }
+        }
+        return false;
+    }
+    /** The mine counter: nothing left to find, everything left a mine, or a clue that accounts for all that remain. */
+    counter() {
+        const covered = [];
+        for (let cell = 0; cell < this.cells; cell += 1)
+            if (this.state[cell] === COVERED)
+                covered.push(cell);
+        if (covered.length === 0)
+            return false;
+        const depth = this.deepestMine + 1;
+        if (this.left === 0 || this.left === covered.length) {
+            this.settle(covered, this.left === 0, depth, "total");
+            return true;
+        }
+        for (let cell = 0; cell < this.cells; cell += 1) {
+            if (this.state[cell] !== OPEN || this.unknown[cell] === 0)
+                continue;
+            const outside = covered.length - this.unknown[cell], mines = this.left - this.need[cell];
+            if (outside === 0 || (mines !== 0 && mines !== outside))
+                continue;
+            const mark = ++this.stamp;
+            for (const n of this.adjacent[cell])
+                if (this.state[n] === COVERED)
+                    this.marks[n] = mark;
+            this.settle(covered.filter((n) => this.marks[n] !== mark), mines === 0, 1 + Math.max(depth - 1, this.chain[cell]), "total");
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Exact enumeration of every frontier small enough, as `enumerateForced` does. Every component is read from the
+     * same position and the answers are applied together, exactly as one `deduce` call does, so that this solver and
+     * the hint engine finish the same boards: with a cap on the size of a frontier, the order of enumerating matters.
+     */
+    enumerate() {
+        const round = ++this.stamp;
+        const found = [];
+        for (let start = 0; start < this.cells; start += 1) {
+            if (this.state[start] !== OPEN || this.unknown[start] === 0 || this.visit[start] === round)
+                continue;
+            const clues = [start];
+            this.visit[start] = round;
+            const cells = new Set();
+            for (let at = 0; at < clues.length; at += 1)
+                for (const x of this.adjacent[clues[at]]) {
+                    if (this.state[x] !== COVERED || cells.has(x))
+                        continue;
+                    cells.add(x);
+                    for (const other of this.adjacent[x])
+                        if (this.state[other] === OPEN && this.visit[other] !== round) {
+                            this.visit[other] = round;
+                            clues.push(other);
+                        }
+                }
+            if (cells.size > 18 || clues.every((c) => this.searched[c]))
+                continue;
+            clues.sort((a, b) => a - b);
+            const constraints = clues.map((c) => ({ cells: this.adjacent[c].filter((n) => this.state[n] === COVERED), mines: this.need[c], sources: [c] }));
+            const result = enumerateForced(constraints);
+            if (result.contradiction) {
+                this.broken = true;
+                return false;
+            }
+            if (result.safe.length === 0 && result.mines.length === 0) {
+                for (const c of clues)
+                    this.searched[c] = 1;
+                continue;
+            }
+            found.push({ mines: [...result.mines], safe: [...result.safe], depth: 1 + clues.reduce((most, c) => Math.max(most, this.chain[c]), 0) });
+        }
+        for (const one of found)
+            this.settle(one.mines, false, one.depth, "enumeration");
+        for (const one of found)
+            this.settle(one.safe, true, one.depth, "enumeration");
+        return found.length > 0;
+    }
+}

package/dist/strings.d.ts

@@ -1,4 +1,5 @@
 import type { Language } from "./jirai.types.ts";
+/** Built-in English and Japanese strings used by the player and renderer. */
 export declare const STRINGS: {
     readonly en: {
         readonly board: "Minesweeper board";
@@ -67,4 +68,5 @@ export declare const STRINGS: {
         readonly error: "推測なしで解ける盤が見つかりませんでした。別のシード、別の開始マス、または少ない地雷で試してください。";
     };
 };
+/** Returns the built-in interface strings for a locale. */
 export declare function words(language?: Language): typeof STRINGS["en"] | typeof STRINGS["ja"];

package/dist/strings.js

@@ -1,3 +1,4 @@
+/** Built-in English and Japanese strings used by the player and renderer. */
 export const STRINGS = {
     en: {
         board: "Minesweeper board", covered: "covered", flag: "flagged", question: "uncertain", empty: "empty", mine: "mine", wrong: "incorrect flag",
@@ -14,4 +15,5 @@ export const STRINGS = {
         error: "推測なしで解ける盤が見つかりませんでした。別のシード、別の開始マス、または少ない地雷で試してください。",
     },
 };
+/** Returns the built-in interface strings for a locale. */
 export function words(language = "en") { return STRINGS[language]; }

package/dist/ui.types.d.ts

@@ -1,10 +1,12 @@
 import type { Game, Language, Material, Pieces, Settings } from "./jirai.types.ts";
+/** Appearance and optional hint marker used by drawing and play. */
 export type DrawOptions = {
     material?: Material;
     pieces?: Pieces;
     language?: Language;
     hint?: number | null;
 };
+/** Accessible presentation data for one active board cell. */
 export type CellModel = {
     cell: number;
     x: number;
@@ -16,11 +18,13 @@ export type CellModel = {
     kind: string;
     hint: boolean;
 };
+/** Layout and cell presentation returned by `boardModel`. */
 export type BoardModel = {
     width: number;
     height: number;
     cells: CellModel[];
 };
+/** Initial game, appearance, control, and lifecycle callbacks for a mounted board. */
 export type MountOptions = DrawOptions & {
     settings?: Settings;
     progress?: string;
@@ -29,6 +33,7 @@ export type MountOptions = DrawOptions & {
     onFinish?: (game: Game) => void;
     onError?: (error: Error) => void;
 };
+/** Controls for reading and operating a mounted board. */
 export type JiraiMount = {
     game: () => Game;
     progress: () => string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@johnmorrisdotca/jirai",
-  "version": "0.2.0",
-  "description": "Minesweeper on square, hexagonal and wraparound boards: 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.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.",
   "type": "module",
   "license": "MIT",
   "author": "John Morris",
@@ -15,14 +15,39 @@
   },
   "keywords": [
     "minesweeper",
-    "puzzle",
-    "hexagonal",
-    "orthogonal",
+    "mines",
+    "minefield",
+    "logic-puzzle",
+    "deduction-puzzle",
+    "number-clues",
+    "hexagonal-minesweeper",
+    "hex-grid",
+    "orthogonal-minesweeper",
+    "four-neighbour",
+    "four-neighbor",
+    "eight-neighbour",
+    "eight-neighbor",
+    "wraparound-grid",
     "no-guess",
+    "no-guess-minesweeper",
+    "difficulty-levels",
+    "seeded-puzzle",
+    "daily-puzzle",
+    "puzzle-generator",
+    "puzzle-solver",
     "typescript",
-    "seeded",
+    "javascript",
+    "svg",
+    "accessible",
+    "keyboard",
+    "touch",
     "web-component",
-    "itsutsu"
+    "custom-element",
+    "react-component",
+    "zero-dependencies",
+    "board-game",
+    "logic-game",
+    "grid-game"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -62,6 +87,7 @@
   "files": [
     "dist",
     "src",
+    "!src/**/*.test.ts",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -74,11 +100,13 @@
     "typecheck": "tsc -p tsconfig.check.json",
     "lint": "eslint .",
     "test": "vitest run",
-    "check": "pnpm lint && pnpm typecheck && pnpm test",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm check:presentation",
     "site": "pnpm build && node scripts/site.mjs",
     "test:demo": "pnpm site && playwright test",
     "test:package": "pnpm build && node scripts/check-package.mjs",
-    "prepublishOnly": "pnpm check && pnpm test:package"
+    "prepublishOnly": "pnpm check && pnpm test:package",
+    "check:presentation": "node scripts/check-presentation.mjs",
+    "pictures": "pnpm site && node scripts/readme-pictures.mjs"
   },
   "peerDependencies": {
     "react": ">=18"

package/src/element.ts

@@ -5,6 +5,7 @@ import type { JiraiMount } from "./ui.types.ts";
 
 // Importing this file on a server is harmless; only defineJirai registers the tag.
 const ElementBase = typeof HTMLElement === "undefined" ? class {} as typeof HTMLElement : HTMLElement;
+/** Configurable `<jirai-board>` element that owns its mounted game. */
 export class JiraiElement extends ElementBase {
   private mounted: JiraiMount | null = null;
   static observedAttributes = ["width", "height", "mines", "seed", "grid", "shape", "no-guess", "material", "pieces", "lang"];
@@ -21,4 +22,5 @@ export class JiraiElement extends ElementBase {
     } catch (error) { this.dispatchEvent(new CustomEvent("jirai-error", { detail: error })); }
   }
 }
+/** Registers the `<jirai-board>` custom element once in a registry. */
 export function defineJirai(registry: CustomElementRegistry = customElements): void { if (!registry.get("jirai-board")) registry.define("jirai-board", JiraiElement); }

package/src/family.test.js

@@ -0,0 +1,105 @@
+// family.test.js: what every package of the family holds the same way, held by one test copied unchanged into
+// each repository (src/family.test.js, or test/family.test.js in Kyuubu). It reads files and runs nothing else.
+// Changing a shared file means changing it in every repository, with the new hash recorded here.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { familyBlockOf, familyReadmeBlock } from "../scripts/family-readme.mjs";
+import { FAMILY, FAMILY_PITCH, FAMILY_TEMPLATE_VERSION } from "../scripts/family-template.mjs";
+import { releaseNotes } from "../scripts/release-notes.mjs";
+
+const read = (path) => readFileSync(path, "utf8").replace(/\r\n/g, "\n");
+const sha = (path) => createHash("sha256").update(readFileSync(path)).digest("hex");
+const pkg = JSON.parse(read("package.json"));
+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" };
+const FILES = {
+  "scripts/family-readme.mjs": "3c9d5b2cbf17a92d31bced98edac7f544616edb0dff90bf2d141722a9d4516c5",
+  "scripts/release-notes.mjs": "efab0fb78ad05973a8885624c0d2ce3b458b55799c11eabaa5176603ce8cd1e9",
+  "scripts/community/SECURITY.md": "ff6f650be7789396233671d2558439736efe7f96a1d1d39115dd5cf94d29275c",
+  "scripts/community/CODE_OF_CONDUCT.md": "34da1f56f004ce8f7f95d4449b64d2ecb5827dd9f0d4eea1da351a20713ebe70",
+};
+
+describe("the family template", () => {
+  it("is the one file, byte for byte, in every package", () => {
+    expect(FAMILY_TEMPLATE_VERSION).toBe(TEMPLATE.version);
+    expect(sha("scripts/family-template.mjs")).toBe(TEMPLATE.sha256);
+  });
+
+  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",
+    ]);
+    for (const one of FAMILY) {
+      expect(one.name, one.id).toBe(one.id[0].toUpperCase() + one.id.slice(1));
+      expect(one.kana, one.id).toMatch(/\S/);
+      expect(FAMILY_PITCH[one.id], one.id).toMatch(/^[^A-Z.].*[^.]$/);
+    }
+    expect(Object.keys(FAMILY_PITCH).sort()).toEqual(FAMILY.map((one) => one.id).sort());
+    expect(FAMILY.map((one) => one.id)).toContain(id);
+  });
+
+  it("is what this package's footer reads: the demo site names the family through it", () => {
+    expect(read("scripts/site.mjs")).toContain("familyFooter(");
+  });
+});
+
+describe("the files every package shares", () => {
+  it("are copied unchanged: the README writer, the release notes, and the family's SECURITY.md and CODE_OF_CONDUCT.md", () => {
+    for (const [path, hash] of Object.entries(FILES)) expect(sha(path), path).toBe(hash);
+  });
+
+  it("SECURITY.md and CODE_OF_CONDUCT.md are the master text of github.com/johnmorrisdotca/.github, which scripts/community keeps a copy of", () => {
+    for (const file of ["SECURITY.md", "CODE_OF_CONDUCT.md"]) expect(read(file), file).toBe(read(`scripts/community/${file}`));
+  });
+});
+
+describe("the README's family", () => {
+  const readme = read("README.md");
+
+  it("is the block scripts/family-readme.mjs writes from the template, under a heading of its own", () => {
+    const block = familyBlockOf(readme);
+    expect(block, "README.md has no family markers").not.toBeNull();
+    expect(block).toBe(familyReadmeBlock(id));
+    expect(readme.split("<!-- family:start").length - 1).toBe(1);
+    expect(readme).toMatch(/\n#{2,3} The family\n+<!-- family:start/);
+  });
+
+  it("names every package once, as a link", () => {
+    const block = familyBlockOf(readme);
+    for (const one of FAMILY) expect(block.split(`](https://github.com/johnmorrisdotca/${one.id})`).length - 1, one.id).toBe(1);
+  });
+});
+
+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);
+    const workflow = read(".github/workflows/release.yml");
+    expect(workflow).toContain("scripts/release-notes.mjs");
+    expect(workflow).not.toContain("See CHANGELOG.md.");
+  });
+
+  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);
+    expect(log).not.toMatch(/^## \d/m);
+  });
+});
+
+describe("Node", () => {
+  it("is 22 or later: engines, the CI matrix, and the words in the README and CONTRIBUTING", () => {
+    expect(pkg.engines.node).toBe(">=22");
+    expect(read(".github/workflows/ci.yml")).toMatch(/node: \[22, 24\]/);
+    expect(read(".github/workflows/ci.yml")).not.toMatch(/node: \[[^\]]*\b(18|20)\b/);
+    for (const file of ["README.md", "CONTRIBUTING.md"]) expect(read(file), file).not.toMatch(/\bNode(\.js)? (v)?(18|20)\b|>= ?20\b/);
+  });
+});

package/src/game.ts

@@ -5,6 +5,7 @@ import { DEFAULT_SETTINGS, MARKS, MOVES, STATUSES } from "./jirai.constants.ts";
 import { neighbours, neighboursOf, validCell, validSettings } from "./grid.ts";
 import type { Board, Game, Move, Settings, VisibleGame } from "./jirai.types.ts";
 
+/** Creates an unstarted game with covered cells and no dealt answer. */
 export function newGame(settings: Settings = DEFAULT_SETTINGS): Game {
   if (!validSettings(settings)) throw new RangeError("Invalid Minesweeper settings.");
   return { settings: { ...settings }, board: null, marks: Array.from({ length: settings.width * settings.height }, () => MARKS.covered), status: STATUSES.ready, exploded: null, moves: [], helped: false };
@@ -16,7 +17,7 @@ export function visibleGame(game: Game): VisibleGame {
     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: Game, board: Board): Game {
   if (game.board !== null || (game.settings.shape ?? "rectangle") !== (board.settings.shape ?? "rectangle") || (Object.keys(DEFAULT_SETTINGS) as (keyof Settings)[]).some(key => game.settings[key] !== board.settings[key])) throw new Error("The board does not belong to this game.");
   return { ...game, board };