@johnmorrisdotca/jirai 0.2.0 → 0.3.0

package/src/generate.ts

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

package/src/grid.ts

@@ -17,6 +17,7 @@ export function validSettings(value: unknown): value is Settings {
     && (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: Settings, cell: number): boolean {
   return Number.isInteger(cell) && cell >= 0 && cell < settings.width * settings.height && activeCell(settings, cell);
 }
@@ -37,6 +38,7 @@ export function neighbours(settings: Settings, cell: number): number[] {
   }
   return [...out].sort((a, b) => a - b);
 }
+/** Precomputes the neighbour list for each row-major cell. */
 export function neighboursOf(settings: Settings): number[][] {
   return Array.from({ length: settings.width * settings.height }, (_, cell) => neighbours(settings, cell));
 }

package/src/index.ts

@@ -7,8 +7,14 @@ export * from "./game.ts";
 export * from "./deduce.ts";
 export * from "./keep.ts";
 export { seededRandom } from "./random.ts";
-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.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/src/jirai.constants.ts

@@ -1,26 +1,49 @@
 import type { Grid, Settings } from "./jirai.types.ts";
 
+/** Names for the supported square, four-neighbour, hex, and wrap grids. */
 export const GRIDS = { square: "square", orthogonal: "orthogonal", hex: "hex", wrap: "wrap" } as const;
+/** Names for the game lifecycle states. */
 export const STATUSES = { ready: "ready", playing: "playing", won: "won", lost: "lost" } as const;
+/** Names for the cell mark cycle. */
 export const MARKS = { covered: "covered", flag: "flag", question: "question", open: "open" } as const;
+/** Names for the moves accepted by the engine. */
 export const MOVES = { reveal: "reveal", mark: "mark", chord: "chord" } as const;
-/** 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: Record<Grid, { offsets: readonly (readonly [number, number])[]; wrap: boolean }> = {
   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"] as const;
+/** 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" } as const;
+/** Size and mine count of each level on a rectangular board. Shaped boards keep the size and the density. */
+export const LEVEL_SIZES: Record<(typeof LEVELS)[number], { width: number; height: number; mines: number }> = {
+  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 },
 } as const;
-export const DEFAULT_SETTINGS: 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: 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/src/jirai.types.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,12 +22,15 @@ 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. */
@@ -34,6 +44,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. */
@@ -41,7 +52,9 @@ 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[];
@@ -50,7 +63,15 @@ export type Deduction = {
   /** A conflicting clue, or a board with no consistent mine placement. */
   contradiction: boolean;
 };
-export type GenerationOptions = { attempts?: number; enumerate?: 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/src/levels.ts

@@ -0,0 +1,31 @@
+import { LEVEL_ALIASES, LEVEL_SIZES, LEVELS } from "./jirai.constants.ts";
+import { activeCells } from "./shape.ts";
+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 function levelNamed(name: unknown): Level | null {
+  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 as LevelAlias];
+  return (LEVELS as readonly string[]).includes(key) ? key as 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 function levelSettings(level: Level | LevelAlias, board: { grid?: Grid; shape?: Settings["shape"] } = {}): LevelSize {
+  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 } as const;
+  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/src/measure.ts

@@ -0,0 +1,44 @@
+import { Solver } from "./solve.ts";
+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 function measureBoard(board: Board): Measure {
+  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/src/orthogonal.ts

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

package/src/react.tsx

@@ -2,7 +2,7 @@ import { useEffect, useRef } from "react";
 import { mountJirai } from "./mount.ts";
 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 function JiraiBoard({ settings, progress, material, pieces, language, controls, onChange, onFinish, onError, ...element }: JiraiProps) {
   const host = useRef<HTMLDivElement>(null);
   const latest = useRef({ onChange, onFinish, onError });

package/src/react.types.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/src/repair.ts

@@ -0,0 +1,88 @@
+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 };
+
+/** 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<T>(items: readonly T[], random: () => number): T | undefined {
+  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: Solver, mines: Uint8Array, clues: Int8Array, from: number, to: number): void {
+  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: Solver, mines: Uint8Array, clues: Int8Array, first: number, pinned: ReadonlySet<number>, random: () => number, budget: number, enumerate: boolean, restart: () => void): RepairOutcome {
+  const around = (cell: number, radius: number): number[] => {
+    const seen = new Set([cell]);
+    let ring = [cell];
+    for (let step = 0; step < radius; step += 1) {
+      const next: number[] = [];
+      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: number[] = [], covered: number[] = [], cutOff: number[] = [];
+    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: number | undefined, to: number | undefined;
+    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/src/shape.ts

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