@johnmorrisdotca/jirai 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [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
+
+- Square, hexagonal and wraparound fields, seeded and configurable.
+- Safe and clear openings, verified no-guess generation and explained deductions.
+- Immutable rules, versioned saved games, daily seeds and separate browser worker.
+- Configurable materials and markers, English/Japanese controls, keyboard and touch play.
+- Plain-DOM mounting, optional React component and custom element.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Morris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# Jirai 地雷
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**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.
+
+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.
+
+## What it does
+
+- 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.
+
+## Start a game
+
+Once published:
+
+```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";
+
+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));
+```
+
+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.
+
+`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.
+
+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.
+
+The demo uses the family’s original shared stylesheet and header template, with its five table-cloth choices and bilingual Help controls.
+
+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.
+
+```ts
+import { mountJirai } from "@johnmorrisdotca/jirai/play";
+
+const board = mountJirai(document.querySelector<HTMLElement>("#board")!, {
+  settings: { ...DEFAULT_SETTINGS, grid: "hex", 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 */ },
+});
+
+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 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:
+
+```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>
+```
+
+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.
+
+## Keep a game
+
+```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");
+```
+
+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 no-guess promise
+
+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.
+
+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.
+
+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.
+
+## Build and check
+
+```sh
+pnpm install
+pnpm check
+pnpm test:package
+pnpm exec playwright install chromium
+pnpm test:demo
+pnpm site
+node scripts/serve.mjs
+```
+
+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.
+
+## Architecture
+
+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`.
+
+Drawing and play: `draw.ts`, `style.ts`, `strings.ts`, `mount.ts`, `worker.ts`, `ui.types.ts`. Framework and tag wrappers are separate entries.
+
+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.
+
+## References
+
+[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.
+
+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.
+
+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.

package/dist/deduce.d.ts

@@ -0,0 +1,8 @@
+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;
+/** 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

@@ -0,0 +1,85 @@
+import { enumerateForced } from "./enumerate.js";
+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);
+    const constraints = [];
+    const empty = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
+    for (let cell = 0; cell < game.clues.length; cell += 1) {
+        const clue = game.clues[cell];
+        if (clue === null || clue === undefined || clue < 0)
+            continue;
+        const unknown = adjacent[cell].filter((n) => game.clues[n] === null && !knownMines.has(n));
+        const mines = clue - adjacent[cell].filter((n) => knownMines.has(n)).length;
+        if (mines < 0 || mines > unknown.length)
+            return { ...empty, contradiction: true };
+        if (unknown.length)
+            constraints.push({ cells: unknown, mines, sources: [cell] });
+    }
+    const unknown = game.clues.flatMap((clue, cell) => clue === null && !knownMines.has(cell) ? [cell] : []);
+    const left = game.settings.mines - knownMines.size;
+    if (left < 0 || left > unknown.length)
+        return { ...empty, contradiction: true };
+    const total = { cells: unknown, mines: left, sources: [] };
+    function forced(c, reason) {
+        if (c.mines === 0)
+            return { ...empty, safe: c.cells, reason, sources: c.sources };
+        if (c.mines === c.cells.length)
+            return { ...empty, mines: c.cells, reason, sources: c.sources };
+        return null;
+    }
+    for (const c of constraints) {
+        const result = forced(c, "count");
+        if (result !== null)
+            return result;
+    }
+    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 = {
+                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.
+    return enumerate ? enumerateForced(constraints) : empty;
+}
+/** Keep discovering certain mines until there is a safe cell or nothing more is proved. */
+export function hintFor(game) {
+    const known = new Set();
+    let last = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
+    while (known.size <= game.settings.mines) {
+        const result = deduce(game, known);
+        if (result.contradiction || result.safe.length)
+            return result;
+        const fresh = result.mines.filter((cell) => !known.has(cell));
+        if (!fresh.length)
+            return last;
+        last = result;
+        for (const cell of fresh)
+            known.add(cell);
+    }
+    return last;
+}

package/dist/draw-entry.d.ts

@@ -0,0 +1,3 @@
+export { boardModel } from "./draw.ts";
+export type { BoardModel, CellModel, DrawOptions } from "./ui.types.ts";
+export { JIRAI_STYLE } from "./style.ts";

package/dist/draw-entry.js

@@ -0,0 +1,2 @@
+export { boardModel } from "./draw.js";
+export { JIRAI_STYLE } from "./style.js";

package/dist/draw.d.ts

@@ -0,0 +1,4 @@
+import type { Game } from "./jirai.types.ts";
+import type { BoardModel, DrawOptions } from "./ui.types.ts";
+/** Where the cells sit, and what may be shown. The drawing never exposes a covered clue. */
+export declare function boardModel(game: Game, options?: DrawOptions): BoardModel;

package/dist/draw.js

@@ -0,0 +1,26 @@
+import { activeCell } from "./shape.js";
+import { GRIDS, MARKS, STATUSES } from "./jirai.constants.js";
+import { words } from "./strings.js";
+/** Where the cells sit, and what may be shown. The drawing never exposes a covered clue. */
+export function boardModel(game, options = {}) {
+    const hex = game.settings.grid === GRIDS.hex;
+    const ended = game.status === STATUSES.lost || game.status === STATUSES.won;
+    const say = words(options.language);
+    const width = hex ? game.settings.width + (game.settings.height - 1) / 2 : game.settings.width;
+    const height = hex ? (game.settings.height - 1) * .866 + 1.155 : game.settings.height;
+    const cells = game.marks.flatMap((mark, cell) => {
+        if (!activeCell(game.settings, cell))
+            return [];
+        const col = cell % game.settings.width, row = Math.floor(cell / game.settings.width);
+        const mine = ended && game.board?.mines[cell] === true;
+        const wrong = ended && mark === MARKS.flag && !mine;
+        const clue = mark === MARKS.open ? game.board?.clues[cell] ?? 0 : 0;
+        const kind = cell === game.exploded ? "exploded" : mine ? "mine" : wrong ? "wrong" : mark;
+        const text = mine ? "✹" : wrong ? "×" : mark === MARKS.flag ? options.pieces === "stones" ? "●" : options.pieces === "flowers" ? "✿" : "⚑"
+            : mark === MARKS.question ? "?" : mark === MARKS.open && clue > 0 ? String(clue) : "";
+        const description = mine ? say.mine : wrong ? say.wrong : mark === MARKS.open ? clue === 0 ? say.empty : `${clue}` : say[mark];
+        return [{ cell, x: col + (hex ? row / 2 : 0), y: row * (hex ? .866 : 1), width: 1, height: hex ? 1.155 : 1,
+                label: `${row + 1}, ${col + 1}: ${description}`, text, kind, hint: options.hint === cell }];
+    });
+    return { width, height, cells };
+}

package/dist/element-define.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/element-define.js

@@ -0,0 +1,3 @@
+import { defineJirai } from "./element.js";
+if (typeof customElements !== "undefined")
+    defineJirai();

package/dist/element.d.ts

@@ -0,0 +1,14 @@
+declare const ElementBase: {
+    new (): HTMLElement;
+    prototype: HTMLElement;
+};
+export declare class JiraiElement extends ElementBase {
+    private mounted;
+    static observedAttributes: string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    private mount;
+}
+export declare function defineJirai(registry?: CustomElementRegistry): void;
+export {};

package/dist/element.js

@@ -0,0 +1,28 @@
+import { DEFAULT_SETTINGS } from "./jirai.constants.js";
+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;
+export class JiraiElement extends ElementBase {
+    mounted = null;
+    static observedAttributes = ["width", "height", "mines", "seed", "grid", "shape", "no-guess", "material", "pieces", "lang"];
+    connectedCallback() { this.mount(); }
+    disconnectedCallback() { this.mounted?.destroy(); this.mounted = null; }
+    attributeChangedCallback() { if (this.isConnected)
+        this.mount(); }
+    mount() {
+        this.mounted?.destroy();
+        this.mounted = null;
+        try {
+            this.mounted = mountJirai(this, {
+                settings: { ...DEFAULT_SETTINGS, width: Number(this.getAttribute("width") ?? DEFAULT_SETTINGS.width), height: Number(this.getAttribute("height") ?? DEFAULT_SETTINGS.height), mines: Number(this.getAttribute("mines") ?? DEFAULT_SETTINGS.mines), seed: Number(this.getAttribute("seed") ?? DEFAULT_SETTINGS.seed), shape: (this.getAttribute("shape") ?? "rectangle"), grid: (this.getAttribute("grid") ?? "square"), noGuess: this.getAttribute("no-guess") !== "false" },
+                material: (this.getAttribute("material") ?? "ivory"), pieces: (this.getAttribute("pieces") ?? "flags"), language: (this.getAttribute("lang") ?? "en"),
+            });
+        }
+        catch (error) {
+            this.dispatchEvent(new CustomEvent("jirai-error", { detail: error }));
+        }
+    }
+}
+export function defineJirai(registry = customElements) { if (!registry.get("jirai-board"))
+    registry.define("jirai-board", JiraiElement); }

package/dist/enumerate.d.ts

@@ -0,0 +1,6 @@
+import type { Constraint, Deduction } from "./jirai.types.ts";
+/**
+ * Exact assignments within a small connected frontier. If the work budget is
+ * reached, none of the partial search is evidence: it returns no deductions.
+ */
+export declare function enumerateForced(constraints: readonly Constraint[]): Deduction;

package/dist/enumerate.js

@@ -0,0 +1,83 @@
+import { ENUMERATION_CELLS, ENUMERATION_NODES } from "./jirai.constants.js";
+/**
+ * Exact assignments within a small connected frontier. If the work budget is
+ * reached, none of the partial search is evidence: it returns no deductions.
+ */
+export function enumerateForced(constraints) {
+    const empty = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
+    const remaining = new Set(constraints.flatMap((c) => [...c.cells]));
+    const safe = [], mines = [], sources = new Set();
+    while (remaining.size > 0) {
+        const component = new Set([remaining.values().next().value]);
+        let grew = true;
+        while (grew) {
+            grew = false;
+            for (const c of constraints) {
+                if (!c.cells.some((cell) => component.has(cell)))
+                    continue;
+                for (const cell of c.cells)
+                    if (!component.has(cell)) {
+                        component.add(cell);
+                        grew = true;
+                    }
+            }
+        }
+        for (const cell of component)
+            remaining.delete(cell);
+        if (component.size > ENUMERATION_CELLS)
+            continue;
+        const cells = [...component];
+        const relevant = constraints.filter((c) => c.cells.some((cell) => component.has(cell)));
+        const positions = relevant.map((c) => c.cells.map((cell) => cells.indexOf(cell)));
+        const assigned = new Int8Array(cells.length).fill(-1);
+        const seenMine = new Uint8Array(cells.length), seenSafe = new Uint8Array(cells.length);
+        let nodes = 0, solutions = 0, stopped = false;
+        function visit(at) {
+            nodes += 1;
+            if (nodes > ENUMERATION_NODES) {
+                stopped = true;
+                return;
+            }
+            for (let i = 0; i < relevant.length; i += 1) {
+                let filled = 0, unknown = 0;
+                for (const p of positions[i]) {
+                    if (assigned[p] === -1)
+                        unknown += 1;
+                    else
+                        filled += assigned[p];
+                }
+                if (filled > relevant[i].mines || filled + unknown < relevant[i].mines)
+                    return;
+            }
+            if (at === cells.length) {
+                solutions += 1;
+                for (let i = 0; i < cells.length; i += 1)
+                    (assigned[i] === 1 ? seenMine : seenSafe)[i] = 1;
+                return;
+            }
+            assigned[at] = 0;
+            visit(at + 1);
+            if (!stopped) {
+                assigned[at] = 1;
+                visit(at + 1);
+            }
+            assigned[at] = -1;
+        }
+        visit(0);
+        if (stopped)
+            continue;
+        if (solutions === 0)
+            return { ...empty, contradiction: true };
+        for (let i = 0; i < cells.length; i += 1) {
+            if (!seenMine[i])
+                safe.push(cells[i]);
+            if (!seenSafe[i])
+                mines.push(cells[i]);
+        }
+        if (safe.length || mines.length)
+            for (const c of relevant)
+                for (const source of c.sources)
+                    sources.add(source);
+    }
+    return { ...empty, safe, mines, sources: [...sources], reason: safe.length || mines.length ? "enumeration" : "none" };
+}

package/dist/flood.d.ts

@@ -0,0 +1,2 @@
+/** Reveal connected empty ground and its numbered boundary, without recursion. */
+export declare function flood(clues: readonly number[], adjacent: readonly (readonly number[])[], open: boolean[], starts: readonly number[], blocked?: ReadonlySet<number>): void;

package/dist/flood.js

@@ -0,0 +1,18 @@
+/** Reveal connected empty ground and its numbered boundary, without recursion. */
+export function flood(clues, adjacent, open, starts, blocked = new Set()) {
+    const queue = [...starts];
+    const queued = new Set(queue);
+    for (let at = 0; at < queue.length; at += 1) {
+        const cell = queue[at];
+        if (open[cell] || blocked.has(cell) || clues[cell] === undefined || clues[cell] < 0)
+            continue;
+        open[cell] = true;
+        if (clues[cell] !== 0)
+            continue;
+        for (const n of adjacent[cell])
+            if (!open[n] && !queued.has(n)) {
+                queue.push(n);
+                queued.add(n);
+            }
+    }
+}

package/dist/game.d.ts

@@ -0,0 +1,8 @@
+import type { Board, Game, Move, Settings, VisibleGame } from "./jirai.types.ts";
+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. */
+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

@@ -0,0 +1,61 @@
+import { activeCell, activeCells } from "./shape.js";
+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";
+export function newGame(settings = DEFAULT_SETTINGS) {
+    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 };
+}
+/** The clue-only view used by the solver. No hidden mine, including under a flag, survives it. */
+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. */
+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.");
+    return { ...game, board };
+}
+/** A legal move returns a new game; an unavailable move returns the same one. */
+export function play(game, move) {
+    if (!validCell(game.settings, move.cell) || game.status === STATUSES.won || game.status === STATUSES.lost)
+        return game;
+    const before = game.marks[move.cell];
+    if (move.kind === MOVES.mark) {
+        if (before === MARKS.open)
+            return game;
+        const marks = [...game.marks];
+        marks[move.cell] = before === MARKS.covered ? MARKS.flag : before === MARKS.flag ? MARKS.question : MARKS.covered;
+        return { ...game, marks, moves: [...game.moves, { ...move }] };
+    }
+    if (move.kind !== MOVES.reveal && move.kind !== MOVES.chord)
+        return game;
+    if (before === MARKS.flag || (move.kind === MOVES.chord && before !== MARKS.open))
+        return game;
+    const board = game.board ?? makeBoard(game.settings, move.cell);
+    let starts = [move.cell];
+    if (before === MARKS.open) {
+        const around = neighbours(game.settings, move.cell);
+        if (around.filter((cell) => game.marks[cell] === MARKS.flag).length !== board.clues[move.cell])
+            return game;
+        starts = around.filter((cell) => game.marks[cell] !== MARKS.flag && game.marks[cell] !== MARKS.open);
+    }
+    if (!starts.length)
+        return game;
+    const marks = [...game.marks];
+    const exploded = starts.find((cell) => board.mines[cell]) ?? null;
+    const open = marks.map((mark) => mark === MARKS.open);
+    const blocked = new Set(marks.flatMap((mark, cell) => mark === MARKS.flag ? [cell] : []));
+    flood(board.clues, neighboursOf(game.settings), open, starts, blocked);
+    for (let cell = 0; cell < marks.length; cell += 1)
+        if (open[cell])
+            marks[cell] = MARKS.open;
+    if (exploded !== null)
+        marks[exploded] = MARKS.open;
+    const status = exploded !== null ? STATUSES.lost
+        : open.filter(Boolean).length === activeCells(game.settings).length - game.settings.mines ? STATUSES.won : STATUSES.playing;
+    return { ...game, board, marks, status, exploded, moves: [...game.moves, { ...move }] };
+}

package/dist/generate.d.ts

@@ -0,0 +1,10 @@
+import type { Board, GenerationOptions, Settings } from "./jirai.types.ts";
+/** A bounded generator must say it failed, never quietly return a guessing board. */
+export declare class GenerationError extends Error {
+    readonly code: "settings" | "opening" | "exhausted";
+    constructor(code: "settings" | "opening" | "exhausted", message: string);
+}
+/** 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. */
+export declare function makeBoard(settings: Settings, first: number, options?: GenerationOptions): Board;

package/dist/generate.js

@@ -0,0 +1,72 @@
+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 { neighbours, neighboursOf, validCell, validSettings } from "./grid.js";
+import { seededRandom, shuffled } from "./random.js";
+/** A bounded generator must say it failed, never quietly return a guessing board. */
+export class GenerationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "GenerationError";
+    }
+}
+/** 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;
+}
+/** Deal after the first reveal. A seed fixes the whole candidate stream and the accepted board. */
+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));
+    if (available.length < settings.mines)
+        throw new GenerationError("opening", "Too many mines for a safe opening at this 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 random = seededRandom(settings.seed);
+    const adjacent = neighboursOf(settings);
+    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;
+    }
+    throw new GenerationError("exhausted", "No verified board found within the work budget. Try another seed, fewer mines, or a different opening.");
+}