@johnmorrisdotca/jirai 0.2.0 → 0.3.0

package/dist/grid.js

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

package/dist/index.d.ts

@@ -7,6 +7,12 @@ export * from "./game.ts";
 export * from "./deduce.ts";
 export * from "./keep.ts";
 export { seededRandom } from "./random.ts";
-export declare const VERSION = "0.2.0";
+/** Package version, kept in step with the release metadata. */
+export declare const VERSION = "0.3.0";
 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";

package/dist/index.js

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

package/dist/jirai.constants.d.ts

@@ -1,47 +1,66 @@
 import type { Grid, Settings } from "./jirai.types.ts";
+/** Names for the supported square, four-neighbour, hex, and wrap grids. */
 export declare const GRIDS: {
     readonly square: "square";
     readonly orthogonal: "orthogonal";
     readonly hex: "hex";
     readonly wrap: "wrap";
 };
+/** Names for the game lifecycle states. */
 export declare const STATUSES: {
     readonly ready: "ready";
     readonly playing: "playing";
     readonly won: "won";
     readonly lost: "lost";
 };
+/** Names for the cell mark cycle. */
 export declare const MARKS: {
     readonly covered: "covered";
     readonly flag: "flag";
     readonly question: "question";
     readonly open: "open";
 };
+/** Names for the moves accepted by the engine. */
 export declare const MOVES: {
     readonly reveal: "reveal";
     readonly mark: "mark";
     readonly chord: "chord";
 };
-/** Hex coordinates are axial: a row is displaced half a cell to the right. */
+/** Neighbour offsets and edge behaviour for each topology. Hex coordinates are axial: each row is displaced half a cell to the right. */
 export declare const GRID_SPECS: Record<Grid, {
     offsets: readonly (readonly [number, number])[];
     wrap: boolean;
 }>;
+/** The four difficulty levels, easiest first. Each is a larger and denser field than the one before. */
+export declare const LEVELS: readonly ["easy", "medium", "hard", "extra-hard"];
+/** The 0.1 and 0.2 names for the first three levels. They are still accepted wherever a level is. */
+export declare const LEVEL_ALIASES: {
+    readonly beginner: "easy";
+    readonly intermediate: "medium";
+    readonly expert: "hard";
+};
+/** Size and mine count of each level on a rectangular board. Shaped boards keep the size and the density. */
+export declare const LEVEL_SIZES: Record<(typeof LEVELS)[number], {
+    width: number;
+    height: number;
+    mines: number;
+}>;
+/** Common minefield dimensions and mine counts. The levels, their older names, and two shapes of field. */
 export declare const PRESETS: {
     readonly beginner: {
-        readonly width: 9;
-        readonly height: 9;
-        readonly mines: 10;
+        width: number;
+        height: number;
+        mines: number;
     };
     readonly intermediate: {
-        readonly width: 16;
-        readonly height: 16;
-        readonly mines: 40;
+        width: number;
+        height: number;
+        mines: number;
     };
     readonly expert: {
-        readonly width: 30;
-        readonly height: 16;
-        readonly mines: 99;
+        width: number;
+        height: number;
+        mines: number;
     };
     readonly wide: {
         readonly width: 21;
@@ -53,10 +72,36 @@ export declare const PRESETS: {
         readonly height: 21;
         readonly mines: 24;
     };
+    readonly easy: {
+        width: number;
+        height: number;
+        mines: number;
+    };
+    readonly medium: {
+        width: number;
+        height: number;
+        mines: number;
+    };
+    readonly hard: {
+        width: number;
+        height: number;
+        mines: number;
+    };
+    readonly "extra-hard": {
+        width: number;
+        height: number;
+        mines: number;
+    };
 };
+/** Default easy game, with a verified no-guess board and clear opening. */
 export declare const DEFAULT_SETTINGS: Settings;
+/** Largest width or height accepted by settings validation. */
 export declare const MAX_SIDE = 60;
+/** Largest total cell count accepted by settings validation. */
 export declare const MAX_CELLS = 2400;
+/** Default number of random layouts tried before a no-guess deal falls back to repairing the closest one. */
 export declare const GENERATION_ATTEMPTS = 128;
+/** Largest frontier enumerated for exact deductions. */
 export declare const ENUMERATION_CELLS = 18;
+/** Maximum partial assignments checked in one exact deduction search. */
 export declare const ENUMERATION_NODES = 100000;

package/dist/jirai.constants.js

@@ -1,24 +1,47 @@
+/** Names for the supported square, four-neighbour, hex, and wrap grids. */
 export const GRIDS = { square: "square", orthogonal: "orthogonal", hex: "hex", wrap: "wrap" };
+/** Names for the game lifecycle states. */
 export const STATUSES = { ready: "ready", playing: "playing", won: "won", lost: "lost" };
+/** Names for the cell mark cycle. */
 export const MARKS = { covered: "covered", flag: "flag", question: "question", open: "open" };
+/** Names for the moves accepted by the engine. */
 export const MOVES = { reveal: "reveal", mark: "mark", chord: "chord" };
-/** Hex coordinates are axial: a row is displaced half a cell to the right. */
+/** Neighbour offsets and edge behaviour for each topology. Hex coordinates are axial: each row is displaced half a cell to the right. */
 export const GRID_SPECS = {
     square: { offsets: [[-1, -1], [0, -1], [1, -1], [-1, 0], [1, 0], [-1, 1], [0, 1], [1, 1]], wrap: false },
     orthogonal: { offsets: [[0, -1], [-1, 0], [1, 0], [0, 1]], wrap: false },
     hex: { offsets: [[-1, 0], [1, 0], [0, -1], [1, -1], [-1, 1], [0, 1]], wrap: false },
     wrap: { offsets: [[-1, -1], [0, -1], [1, -1], [-1, 0], [1, 0], [-1, 1], [0, 1], [1, 1]], wrap: true },
 };
+/** The four difficulty levels, easiest first. Each is a larger and denser field than the one before. */
+export const LEVELS = ["easy", "medium", "hard", "extra-hard"];
+/** The 0.1 and 0.2 names for the first three levels. They are still accepted wherever a level is. */
+export const LEVEL_ALIASES = { beginner: "easy", intermediate: "medium", expert: "hard" };
+/** Size and mine count of each level on a rectangular board. Shaped boards keep the size and the density. */
+export const LEVEL_SIZES = {
+    easy: { width: 9, height: 9, mines: 10 },
+    medium: { width: 16, height: 16, mines: 40 },
+    hard: { width: 30, height: 16, mines: 99 },
+    "extra-hard": { width: 40, height: 24, mines: 240 },
+};
+/** Common minefield dimensions and mine counts. The levels, their older names, and two shapes of field. */
 export const PRESETS = {
-    beginner: { width: 9, height: 9, mines: 10 },
-    intermediate: { width: 16, height: 16, mines: 40 },
-    expert: { width: 30, height: 16, mines: 99 },
+    ...LEVEL_SIZES,
+    beginner: LEVEL_SIZES.easy,
+    intermediate: LEVEL_SIZES.medium,
+    expert: LEVEL_SIZES.hard,
     wide: { width: 21, height: 9, mines: 24 },
     tall: { width: 9, height: 21, mines: 24 },
 };
-export const DEFAULT_SETTINGS = { ...PRESETS.beginner, grid: GRIDS.square, noGuess: true, opening: "clear", seed: 1 };
+/** Default easy game, with a verified no-guess board and clear opening. */
+export const DEFAULT_SETTINGS = { ...LEVEL_SIZES.easy, grid: GRIDS.square, noGuess: true, opening: "clear", seed: 1 };
+/** Largest width or height accepted by settings validation. */
 export const MAX_SIDE = 60;
+/** Largest total cell count accepted by settings validation. */
 export const MAX_CELLS = 2400;
+/** Default number of random layouts tried before a no-guess deal falls back to repairing the closest one. */
 export const GENERATION_ATTEMPTS = 128;
+/** Largest frontier enumerated for exact deductions. */
 export const ENUMERATION_CELLS = 18;
+/** Maximum partial assignments checked in one exact deduction search. */
 export const ENUMERATION_NODES = 100_000;

package/dist/jirai.types.d.ts

@@ -1,7 +1,14 @@
-/** A cell's number is its row-major place on the board, starting at zero. */
+/** Neighbour topology used to count the clues around each cell. */
 export type Grid = "square" | "orthogonal" | "hex" | "wrap";
+/** A difficulty level: easy, medium, hard or extra-hard. */
+export type Level = "easy" | "medium" | "hard" | "extra-hard";
+/** The 0.1 and 0.2 names for easy, medium and hard, still accepted wherever a level is. */
+export type LevelAlias = "beginner" | "intermediate" | "expert";
+/** Current game state, including whether a mine has been hit. */
 export type Status = "ready" | "playing" | "won" | "lost";
+/** Player-facing state of one cell; the answer is never a mark. */
 export type Mark = "covered" | "flag" | "question" | "open";
+/** Board dimensions and rules used to deal and validate a game. */
 export type Settings = {
     /** Shape omits cells; rectangle is the compatible default. Wrap requires rectangle. */
     shape?: "rectangle" | "heart" | "star" | "hexagon";
@@ -15,15 +22,18 @@ export type Settings = {
     opening: "safe" | "clear";
     seed: number;
 };
+/** A reveal, mark-cycle, or numbered-cell chord applied to a game. */
 export type Move = {
     kind: "reveal" | "mark" | "chord";
     cell: number;
 };
+/** A dealt board including its answer; keep it off public clients. */
 export type Board = {
     settings: Settings;
     mines: readonly boolean[];
     clues: readonly number[];
     first: number;
+    /** Which candidate this deal was: below the `attempts` limit it is a random layout, at or above it a repaired one. */
     attempt: number;
 };
 /** Rules data includes the answer; never send it to a competitive client. Use visibleGame for hints and drawing. */
@@ -37,6 +47,7 @@ export type Game = {
     /** A proved hint has been shown during this run. */
     helped: boolean;
 };
+/** Answer-free state suitable for deductions, hints, and public display. */
 export type VisibleGame = {
     settings: Settings;
     /** Null is hidden, including flags. Only opened cells give a clue. */
@@ -44,11 +55,13 @@ export type VisibleGame = {
     marks: readonly Mark[];
     status: Status;
 };
+/** An exact count over unknown cells, with the clues that supplied it. */
 export type Constraint = {
     cells: readonly number[];
     mines: number;
     sources: readonly number[];
 };
+/** Certain safe cells and mines proved from visible clues. */
 export type Deduction = {
     safe: readonly number[];
     mines: readonly number[];
@@ -57,10 +70,20 @@ export type Deduction = {
     /** A conflicting clue, or a board with no consistent mine placement. */
     contradiction: boolean;
 };
+/**
+ * Work limits for seeded board generation and its no-guess check. `attempts` is the number of random layouts tried
+ * first; `repairs` is how many single-mine moves the repair stage may try on the closest of them (0, or `repair:
+ * false`, keeps the 0.2 behaviour of giving up after the attempts); `enumerate` switches the exact small-frontier check.
+ */
 export type GenerationOptions = {
     attempts?: number;
+    repairs?: number;
+    repair?: boolean;
     enumerate?: boolean;
 };
+/** Supported interface copy locales. */
 export type Language = "en" | "ja";
+/** Board colours for drawing and mounted play. */
 export type Material = "ivory" | "wood" | "slate";
+/** Symbols used to mark mines. */
 export type Pieces = "flags" | "stones" | "flowers";

package/dist/levels.d.ts

@@ -0,0 +1,16 @@
+import type { Grid, Level, LevelAlias, Settings } from "./jirai.types.ts";
+/** Board size and mine count a level asks for. */
+export type LevelSize = Pick<Settings, "width" | "height" | "mines">;
+/**
+ * The level a name means, or null. Accepts `easy`, `medium`, `hard` and `extra-hard` (also written `extra hard`,
+ * `extra_hard` or `extraHard`, in any case), and the older `beginner`, `intermediate` and `expert`.
+ */
+export declare function levelNamed(name: unknown): Level | null;
+/**
+ * The size and mine count of a level. A rectangle gets the level's own numbers; a shaped board keeps the level's
+ * width and height and its density of mines over the cells that are left. Throws `RangeError` for a name that is no level.
+ */
+export declare function levelSettings(level: Level | LevelAlias, board?: {
+    grid?: Grid;
+    shape?: Settings["shape"];
+}): LevelSize;

package/dist/levels.js

@@ -0,0 +1,29 @@
+import { 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`,
+ * `extra_hard` or `extraHard`, in any case), and the older `beginner`, `intermediate` and `expert`.
+ */
+export function levelNamed(name) {
+    if (typeof name !== "string")
+        return null;
+    const key = name.trim().toLowerCase().replace(/[\s_]+/g, "-").replace(/^extrahard$/, "extra-hard");
+    if (Object.hasOwn(LEVEL_ALIASES, key))
+        return LEVEL_ALIASES[key];
+    return LEVELS.includes(key) ? key : null;
+}
+/**
+ * The size and mine count of a level. A rectangle gets the level's own numbers; a shaped board keeps the level's
+ * width and height and its density of mines over the cells that are left. Throws `RangeError` for a name that is no level.
+ */
+export function levelSettings(level, board = {}) {
+    const named = levelNamed(level);
+    if (named === null)
+        throw new RangeError(`Unknown level: ${String(level)}`);
+    const size = LEVEL_SIZES[named];
+    if ((board.shape ?? "rectangle") === "rectangle")
+        return { ...size };
+    const probe = { ...size, 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(size.mines / (size.width * size.height) * cells))) };
+}

package/dist/measure.d.ts

@@ -0,0 +1,28 @@
+import type { ProofTally } from "./solve.ts";
+import type { Board } from "./jirai.types.ts";
+/** How demanding a dealt board is to solve by deduction, measured by solving it. */
+export type Measure = {
+    /** Mines per playable cell. */
+    density: number;
+    /** Playable cells. */
+    cells: number;
+    /** Share of the safe cells the first reveal opens before any reasoning. */
+    opening: number;
+    /** Cells proved by each kind of reasoning: one clue, two clues together, the mine counter, or every arrangement of a small frontier. */
+    proofs: ProofTally;
+    /** Share of the playable cells proved by anything beyond one clue's count: the part of the board that needs multi-step reasoning. */
+    multiStep: number;
+    /** The longest chain of deductions, each resting on the one before. */
+    depth: number;
+    /** One number for ranking boards: higher is harder. Not a calibrated rating, but monotone in each part above. */
+    score: number;
+    /** The board can be finished by deduction alone. */
+    solvable: boolean;
+};
+/**
+ * Solve a dealt board from its opening and report what it took. The score is
+ * `100 × density + 100 × multiStep + depth ÷ 4`, so it rises with the crowding of the mines, with the share of the
+ * field that needs more than a single clue, and with how long the longest chain of reasoning runs. It is a way to
+ * put boards in order, not a rating of how long a person will take.
+ */
+export declare function measureBoard(board: Board): Measure;

package/dist/measure.js

@@ -0,0 +1,21 @@
+import { Solver } from "./solve.js";
+/**
+ * Solve a dealt board from its opening and report what it took. The score is
+ * `100 × density + 100 × multiStep + depth ÷ 4`, so it rises with the crowding of the mines, with the share of the
+ * field that needs more than a single clue, and with how long the longest chain of reasoning runs. It is a way to
+ * put boards in order, not a rating of how long a person will take.
+ */
+export function measureBoard(board) {
+    const solver = new Solver(board.settings);
+    const report = solver.run(Int8Array.from(board.clues), board.first, true);
+    const cells = solver.safeTotal + solver.mineTotal;
+    const density = solver.mineTotal / cells;
+    const { count, overlap, total, enumeration } = report.proved;
+    const multiStep = (overlap + total + enumeration) / cells;
+    const opening = solver.safeTotal === 0 ? 0 : report.free / solver.safeTotal;
+    const score = 100 * density + 100 * multiStep + report.depth / 4;
+    return {
+        density, cells, opening, proofs: { count, overlap, total, enumeration }, multiStep, depth: report.depth,
+        score: Math.round(score * 10) / 10, solvable: report.solved,
+    };
+}

package/dist/orthogonal.d.ts

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

package/dist/react.d.ts

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

package/dist/react.js

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

package/dist/react.types.d.ts

@@ -1,3 +1,4 @@
 import type { HTMLAttributes } from "react";
 import type { MountOptions } from "./ui.types.ts";
+/** Mount options plus standard div attributes for the React wrapper. */
 export type JiraiProps = MountOptions & Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "onError">;

package/dist/repair.d.ts

@@ -0,0 +1,14 @@
+import type { Solver } from "./solve.ts";
+/** What a repair run did: whether it reached a board the solver finishes, how many layouts it tried, and how many safe cells it left covered. */
+export type RepairOutcome = {
+    solved: boolean;
+    tries: number;
+    remaining: number;
+};
+/**
+ * Make an unsolvable layout solvable by moving single mines next to the place the solver got stuck, never touching a
+ * pinned cell, and keeping a move when it leaves the solver no worse off (and now and then when it does, so that a
+ * dead end can be left). The search is counted in layouts tried, never in time, so a seed always gives the same board.
+ * `mines` and `clues` are changed in place and hold the answer when the outcome is solved.
+ */
+export declare function repair(solver: Solver, mines: Uint8Array, clues: Int8Array, first: number, pinned: ReadonlySet<number>, random: () => number, budget: number, enumerate: boolean, restart: () => void): RepairOutcome;

package/dist/repair.js

@@ -0,0 +1,112 @@
+/** How readily a move that leaves more safe cells covered is kept, to climb out of a dead end. Small: nearly all such moves are refused. */
+const WARMTH = 0.3;
+/** Tries without getting closer after which the search begins again from a new layout, at least. */
+const PATIENCE = 1500;
+/** How far from the stuck cell a mine may be moved from and to. */
+const REACH = 2;
+function pick(items, random) {
+    return items.length === 0 ? undefined : items[Math.floor(random() * items.length)];
+}
+/** Move a mine from `from` to `to`, keeping every clue in step. Calling it again with the arguments swapped undoes it. */
+function move(solver, mines, clues, from, to) {
+    mines[from] = 0;
+    mines[to] = 1;
+    for (const cell of [from, to]) {
+        const delta = cell === to ? 1 : -1;
+        for (const n of solver.adjacent[cell])
+            if (!mines[n])
+                clues[n] += delta;
+    }
+    clues[to] = -1;
+    let count = 0;
+    for (const n of solver.adjacent[from])
+        if (mines[n])
+            count += 1;
+    clues[from] = count;
+}
+/**
+ * Make an unsolvable layout solvable by moving single mines next to the place the solver got stuck, never touching a
+ * pinned cell, and keeping a move when it leaves the solver no worse off (and now and then when it does, so that a
+ * dead end can be left). The search is counted in layouts tried, never in time, so a seed always gives the same board.
+ * `mines` and `clues` are changed in place and hold the answer when the outcome is solved.
+ */
+export function repair(solver, mines, clues, first, pinned, random, budget, enumerate, restart) {
+    const around = (cell, radius) => {
+        const seen = new Set([cell]);
+        let ring = [cell];
+        for (let step = 0; step < radius; step += 1) {
+            const next = [];
+            for (const c of ring)
+                for (const n of solver.adjacent[c])
+                    if (!seen.has(n)) {
+                        seen.add(n);
+                        next.push(n);
+                    }
+            ring = next;
+        }
+        return [...seen].filter((c) => !pinned.has(c));
+    };
+    let report = solver.run(clues, first, enumerate);
+    let tries = 0, closest = report.remaining, idle = 0;
+    const patience = Math.max(PATIENCE, 2 * solver.cells);
+    while (!report.solved && tries < budget) {
+        tries += 1;
+        const frontier = [], covered = [], cutOff = [];
+        for (let cell = 0; cell < solver.cells; cell += 1) {
+            if (solver.state[cell] !== 0)
+                continue;
+            covered.push(cell);
+            if (solver.adjacent[cell].some((n) => solver.state[n] === 1))
+                frontier.push(cell);
+            else if (!mines[cell] && !pinned.has(cell))
+                cutOff.push(cell);
+        }
+        let from, to;
+        const lost = cutOff.length > 0 && random() < 0.5 ? pick(cutOff, random) : undefined;
+        if (lost !== undefined) {
+            // A safe cell no opened clue touches is walled in by mines. Either wall one in more, or take a wall mine away.
+            const walls = solver.adjacent[lost].filter((n) => mines[n] && !pinned.has(n));
+            if (walls.length > 0 && random() < 0.5) {
+                from = pick(walls, random);
+                to = pick(around(from, REACH).filter((c) => !mines[c]), random);
+            }
+            else {
+                to = lost;
+                from = pick(around(lost, REACH + 1).filter((c) => mines[c]), random);
+            }
+        }
+        else {
+            const focus = pick(frontier.length > 0 ? frontier : covered, random);
+            if (focus === undefined)
+                break;
+            let near = around(focus, REACH);
+            from = pick(near.filter((c) => mines[c]), random);
+            if (from === undefined) {
+                near = around(focus, REACH + 2);
+                from = pick(near.filter((c) => mines[c]), random);
+            }
+            to = pick(near.filter((c) => !mines[c]), random);
+        }
+        if (from === undefined || to === undefined)
+            continue;
+        move(solver, mines, clues, from, to);
+        const next = solver.run(clues, first, enumerate);
+        const worse = next.remaining - report.remaining;
+        if (worse < 0 || (worse === 0 && next.unresolved <= report.unresolved) || (worse > 0 && random() < Math.exp(-worse / WARMTH)))
+            report = next;
+        else
+            move(solver, mines, clues, to, from);
+        if (report.remaining < closest) {
+            closest = report.remaining;
+            idle = 0;
+        }
+        else if (++idle > patience) {
+            // Stuck for a long while in one corner of the search: begin again from a new layout.
+            restart();
+            report = solver.run(clues, first, enumerate);
+            closest = report.remaining;
+            idle = 0;
+        }
+    }
+    return { solved: report.solved, tries, remaining: report.remaining };
+}

package/dist/shape.d.ts

@@ -1,5 +1,7 @@
 import type { Settings } from "./jirai.types.ts";
+/** Board silhouettes supported by settings. */
 export declare const SHAPES: readonly ["rectangle", "heart", "star", "hexagon"];
 /** Row-major addresses stay stable; omitted cells have no clue and no neighbours. */
 export declare function activeCell(settings: Settings, cell: number): boolean;
+/** Returns all active cells in stable row-major order. */
 export declare function activeCells(settings: Settings): number[];

package/dist/shape.js

@@ -1,3 +1,4 @@
+/** Board silhouettes supported by settings. */
 export const SHAPES = ["rectangle", "heart", "star", "hexagon"];
 /** Row-major addresses stay stable; omitted cells have no clue and no neighbours. */
 export function activeCell(settings, cell) {
@@ -28,6 +29,7 @@ export function activeCell(settings, cell) {
         default: return true;
     }
 }
+/** Returns all active cells in stable row-major order. */
 export function activeCells(settings) {
     return Array.from({ length: settings.width * settings.height }, (_, cell) => cell).filter(cell => activeCell(settings, cell));
 }

package/dist/solve.d.ts

@@ -0,0 +1,79 @@
+import type { Settings } from "./jirai.types.ts";
+/** Why a cell was proved: one clue, two overlapping clues, the mine counter, or every arrangement of a small frontier. */
+export type ProofKind = "count" | "overlap" | "total" | "enumeration";
+/** Cells proved by each kind of reasoning. */
+export type ProofTally = Record<ProofKind, number>;
+/** What a run of the deduction solver found. */
+export type SolveReport = {
+    /** Every safe cell was opened using only proved deductions. */
+    solved: boolean;
+    /** Safe cells still covered when the solver stopped; zero when solved. */
+    remaining: number;
+    /** Safe cells opened, including the free opening. */
+    opened: number;
+    /** Covered cells, safe or mine, nothing has been proved about. */
+    unresolved: number;
+    /** Cells opened by the first reveal and its flood, before any deduction. */
+    free: number;
+    /** Cells proved (safe or mine) by each kind of reasoning. */
+    proved: ProofTally;
+    /** The longest chain of deductions, each resting on the one before. */
+    depth: number;
+};
+/**
+ * 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 declare class Solver {
+    readonly settings: Settings;
+    readonly adjacent: readonly (readonly number[])[];
+    readonly cells: number;
+    readonly safeTotal: number;
+    readonly mineTotal: number;
+    readonly state: Uint8Array;
+    private readonly start;
+    private readonly need;
+    private readonly unknown;
+    private readonly chain;
+    private readonly dirty;
+    private readonly searched;
+    private readonly marks;
+    private readonly seen;
+    private readonly visit;
+    private readonly queue;
+    private readonly stack;
+    private clues;
+    private stamp;
+    private covered;
+    private left;
+    private opened;
+    private free;
+    private deepestMine;
+    private depth;
+    private broken;
+    private searching;
+    private proved;
+    constructor(settings: Settings, adjacent?: readonly (readonly number[])[]);
+    /** Clues of a layout: -1 for a mine, -2 outside the shape, otherwise the count of neighbouring mines. */
+    clueFor(mines: ArrayLike<number | boolean>, into?: Int8Array): Int8Array;
+    /** Play the opening at `first` and every deduction after it. `clues` is read, never changed. */
+    run(clues: Int8Array, first: number, enumerate?: boolean): SolveReport;
+    private report;
+    private touch;
+    /** Open a cell known to be safe, and flood through every zero. `kind` null is the free opening. */
+    private reveal;
+    private flag;
+    private settle;
+    /** One deduction from the clue at `cell` alone, or from it and an overlapping clue. */
+    private step;
+    /** The mine counter: nothing left to find, everything left a mine, or a clue that accounts for all that remain. */
+    private counter;
+    /**
+     * 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.
+     */
+    private enumerate;
+}