@johnmorrisdotca/jirai 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-05
+
+- An extra-hard level, 40×24 with 240 mines (25%), joins easy, medium and hard on every rule and outline, and every field is still proved to need no guess. `beginner`, `intermediate` and `expert` stay as names for easy, medium and hard, and `PRESETS` keeps them. New: `LEVELS`, `LEVEL_SIZES`, `LEVEL_ALIASES`, `levelNamed`, `levelSettings` (shaped boards keep a level's size and share of mines) and `measureBoard`, which scores density, multi-step share and depth of deduction so the levels can be shown to step up.
+- No-guess dealing is much faster and no longer fails on dense fields: a one-pass solver that agrees with the hint engine replaces the repeated scans (a 30×16 expert square field took over half a second, now about 2 ms), and when no random layout can be finished the closest is repaired by moving single mines next to where the solver stopped. Orthogonal expert fields, which failed five times in six, are now dealt every time. New options `repairs` and `repair: false` (the 0.2 behaviour of giving up after the random layouts).
+- Every field 0.2.1 dealt is dealt again, identically, for the same seed and settings (pinned by tests), and saved games from 0.2.1 replay unchanged. Only settings that used to throw `GenerationError` deal differently, because they now succeed.
+- Narrowed: a cell with no neighbours under the rules (a tip of an orthogonal or hexagonal star) cannot be opened from without a guess, so an opening there now throws `GenerationError` with code `"opening"`, and unreachable cells are made mines. Nothing else is narrowed: extra-hard is offered on square, orthogonal, hexagonal and wraparound grids and on rectangle, heart, star and hexagon outlines.
+- The demo's Size menu is now Level (easy, medium, hard, extra-hard, wide, tall), in English and Japanese, follows the grid and outline, and reads `?level=` (old names too). The Playwright port can be set with `TEST_PORT`.
+
 ## [0.2.1] - 2026-10-05
 
 - The package no longer ships its unit tests (`src/*.test.ts`) in the npm tarball.

package/README.md

@@ -49,7 +49,8 @@ const board = makeOrthogonalBoard(settings, 40); // counts only edge-sharing nei
 - **Four rule sets:** square grids count eight neighbours, orthogonal grids count four, hex grids count six axial neighbours, and wraparound grids join opposite square edges.
 - **Board outlines:** rectangles, hearts, stars and hexagon outlines. Shaped boards have cut-outs; wraparound works with rectangles.
 - **A fair first move:** choose a safe first cell or a clear opening with all its neighbours safe.
-- **Verified no-guess deals:** optional deduction-only dealing accepts a board only when the solver proves every safe cell from the opening. It throws `GenerationError` when the bounded search cannot prove one.
+- **Four levels:** easy (9×9, 10 mines), medium (16×16, 40), hard (30×16, 99) and extra-hard (40×24, 240), on every rule and outline. The old names `beginner`, `intermediate` and `expert` still work and mean easy, medium and hard.
+- **Verified no-guess deals:** optional deduction-only dealing accepts a board only when the solver proves every safe cell from the opening, even at extra-hard's 25% mines. It throws `GenerationError` when the bounded search cannot prove one.
 - **Fixed seeded fields:** after the opening, mines never move. A seed and settings reproduce the same deal.
 - **Familiar play:** reveal, flag, question-mark, chord, flood-open, explained hint, timer, undo by saved replay, and a just-the-board dialog.
 - **Accessible controls:** keyboard navigation, pointer and touch, long press to mark, English and Japanese strings, and board labels read by assistive technology.
@@ -104,11 +105,37 @@ The optional React entry exports `JiraiBoard` from `@johnmorrisdotca/jirai/react
 | `seed` | Integer from 0 through 4,294,967,295. A seed is interpreted together with all other settings and the first cell. |
 | `material`, `pieces`, `language` | `ivory`, `wood`, `slate`; `flags`, `stones`, `flowers`; `en`, `ja`. |
 
-The built-in presets are beginner (9×9, 10 mines), intermediate (16×16, 40), expert (30×16, 99), wide (21×9, 24), and tall (9×21, 24). They are starting points, not calibrated difficulty ratings.
+## Levels
+
+| Level | Size | Mines | Mines per cell | Old name |
+| --- | --- | --- | --- | --- |
+| `easy` | 9×9 | 10 | 12% | `beginner` |
+| `medium` | 16×16 | 40 | 16% | `intermediate` |
+| `hard` | 30×16 | 99 | 21% | `expert` |
+| `extra-hard` | 40×24 | 240 | 25% | |
+
+`levelNamed(name)` returns the level a name means (`extra-hard` may also be written `extra hard`, `extra_hard` or `extraHard`) or `null`. `levelSettings(level, { grid, shape })` returns `{ width, height, mines }`: a rectangle gets the numbers above, and a heart, star or hexagon outline keeps the level's width and height and its share of mines over the cells that are left. `PRESETS` holds the four levels, the three old names, and `wide` (21×9, 24) and `tall` (9×21, 24).
+
+```ts
+import { DEFAULT_SETTINGS, levelSettings, newGame } from "@johnmorrisdotca/jirai";
+
+const game = newGame({ ...DEFAULT_SETTINGS, ...levelSettings("extra-hard", { grid: "hex", shape: "star" }), grid: "hex", shape: "star", seed: 7 });
+```
+
+The levels step up a measured difficulty. `measureBoard(board)` solves a dealt board with the same deductions the hints use and reports its `density`, the share of cells proved by anything beyond one clue's count (`multiStep`), the longest chain of deductions (`depth`), the cells proved by each kind of reasoning, and a `score` (`100 × density + 100 × multiStep + depth ÷ 4`) that puts boards in order. It is not a prediction of how long a person takes. Mean score of 30 seeds, rectangles, opening in the middle:
+
+| Rule | easy | medium | hard | extra-hard |
+| --- | --- | --- | --- | --- |
+| square (8 neighbours) | 26 | 41 | 63 | 85 |
+| orthogonal (4) | 18 | 26 | 38 | 49 |
+| hexagonal (6) | 21 | 31 | 49 | 65 |
+| wraparound (8) | 25 | 41 | 67 | 96 |
+
+Orthogonal clues carry less information, so its numbers are smaller at every level; each level is still at least a quarter harder than the one before it on every rule.
 
 ## Engine and saved games
 
-`newGame(settings)` returns an immutable ready game with no dealt mines. `play(game, move)` returns a new state; a move that cannot be made returns the original state. `visibleGame(game)` strips hidden mine locations. `hintFor(visibleGame)` reads only opened clues: flags are marks, never evidence. `makeBoard(settings, first, options?)` deals directly, and `isSolvable(board)` independently checks whether its deduction solver can finish.
+`newGame(settings)` returns an immutable ready game with no dealt mines. `play(game, move)` returns a new state; a move that cannot be made returns the original state. `visibleGame(game)` strips hidden mine locations. `hintFor(visibleGame)` reads only opened clues: flags are marks, never evidence. `makeBoard(settings, first, options?)` deals directly, and `isSolvable(board)` independently checks whether its deduction solver can finish. The solver runs the hint engine's deductions to a fixed point in one pass, and is tested to agree with `deduce` on every board.
 
 `gameProgress(game)` saves the settings and move history, not an unchecked answer. `gameFromProgress(code)` replays and validates the moves, returning `null` for invalid data. The original square, hex and wraparound games use version 1 records. Orthogonal games use version 2 with `variant: "orthogonal"`; `decodeOrthogonalGame` accepts only those records. Keep this distinction when storing old games.
 
@@ -122,7 +149,26 @@ Materials are `ivory`, `wood` and `slate`. Marker sets are `flags`, `stones` and
 
 ## Limits and browser support
 
-The board is capped at 60 cells per side and 2,400 cells overall. Shapes need at least 9×9; wraparound is rectangular. The no-guess generator tries at most 128 candidates by default. `makeBoard(settings, first, { attempts })` accepts 1–10,000 attempts and can enable or disable local enumeration with `enumerate`; failure raises `GenerationError` rather than silently returning a guessing field. Very dense or shaped boards may exhaust that budget. For synchronous server use, consider running difficult custom settings in a worker.
+The board is capped at 60 cells per side and 2,400 cells overall. Shapes need at least 9×9; wraparound is rectangular.
+
+**How a no-guess field is dealt.** First the generator draws up to 128 random layouts (`attempts`), exactly as 0.2 did, so every field those versions dealt is dealt again, unchanged, for the same seed. If none of them can be finished by deduction it takes the closest and repairs it: single mines are moved next to the place the solver stopped, a move is kept when it leaves the solver no worse off, and the search starts over from a new layout when it stalls. The work is counted in layouts tried (`repairs`, 12 per cell by default), never in time, so a seed always gives the same field. Every field returned is proved by the same deductions either way; `board.attempt` at or above `attempts` says the field was repaired. `makeBoard(settings, first, { attempts, repairs, repair, enumerate })` accepts 1–10,000 attempts, 0–1,000,000 repairs, `repair: false` for the 0.2 behaviour of giving up after the random layouts, and `enumerate` to switch the exact small-frontier check. Failure raises `GenerationError` rather than returning a guessing field.
+
+**Measured generation** (200 seeds for each rule, outline and level, with the opening on a random cell; Node 24 on one core of a shared laptop, so read the milliseconds as an order of magnitude). Every level on every combination dealt a verified field every time, except for the one case below. The slowest single deal in the whole run was 230 ms; the median at extra-hard, the largest and densest level, was 36 ms for a square rectangle (the slowest median), 25 ms orthogonal, 22 ms hexagonal and 3 ms wraparound; its 95th percentile was at most 55 ms. Before 0.3, orthogonal `expert` boards failed five times in six and square ones took over half a second.
+
+| Level | Median | 95th percentile | Slowest |
+| --- | --- | --- | --- |
+| easy | 0.1–0.5 ms | 0.3–1.1 ms | 3.3 ms |
+| medium | 0.2–1.7 ms | 0.4–3.1 ms | 3.6 ms |
+| hard | 0.6–7.7 ms | 1.2–11.8 ms | 16.7 ms |
+| extra-hard | 3–36 ms | 10–55 ms | 229 ms |
+
+**What a field cannot do, and what is done about it.**
+
+- A cell with no neighbours under the rules (a tip of an orthogonal or hexagonal star) can never be told by a clue. `makeBoard` refuses an opening on one with `GenerationError` code `"opening"` (open another cell), and a field whose opening can reach only part of the outline makes the cut-off cells mines, since nobody has to find a mine to win. This is the only case in which an extra-hard deal fails: 2 of 340 cells on an orthogonal star, 1 on a hexagonal star, 0 on any other outline.
+- Extra-hard is not narrowed for any rule or outline: all of them reach 25% reliably. A custom field much denser than that is still not promised; it raises `GenerationError` when the work budget runs out.
+- The widest fields (30 and 40 columns) scroll sideways inside the board on a narrow screen, as hard always has.
+
+For synchronous server use, consider running a deal in a worker; a browser deals extra-hard in the board's own worker without a pause.
 
 The browser player uses ES modules, SVG, custom elements, dialogs and module workers. Serve built files over HTTP; `file:` pages cannot load its worker. The engine and drawing functions do not need DOM globals. Development and tests require Node 22 or later.
 

package/dist/generate.d.ts

@@ -6,5 +6,11 @@ export declare class GenerationError extends Error {
 }
 /** 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. */
+/**
+ * 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 declare function makeBoard(settings: Settings, first: number, options?: GenerationOptions): Board;

package/dist/generate.js

@@ -1,9 +1,9 @@
-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 { activeCells } from "./shape.js";
+import { GENERATION_ATTEMPTS } from "./jirai.constants.js";
 import { neighbours, neighboursOf, validCell, validSettings } from "./grid.js";
+import { repair } from "./repair.js";
 import { seededRandom, shuffled } from "./random.js";
+import { Solver } from "./solve.js";
 /** A bounded generator must say it failed, never quietly return a guessing board. */
 export class GenerationError extends Error {
     code;
@@ -15,58 +15,89 @@ export class GenerationError extends Error {
 }
 /** 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;
+    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, 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));
+    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 = null, fewest = Infinity;
+    const board = (attempt) => ({
+        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 = { 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 = () => {
+                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/dist/index.d.ts

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

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

@@ -31,22 +31,36 @@ export declare const GRID_SPECS: Record<Grid, {
     offsets: readonly (readonly [number, number])[];
     wrap: boolean;
 }>;
-/** Common minefield dimensions and mine counts. */
+/** 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;
@@ -58,14 +72,34 @@ 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 beginner game, with a verified no-guess board and clear opening. */
+/** 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 candidate-board budget for verified generation. */
+/** 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;

package/dist/jirai.constants.js

@@ -13,21 +13,33 @@ export const GRID_SPECS = {
     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 },
 };
-/** Common minefield dimensions and mine counts. */
+/** 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 },
 };
-/** Default beginner game, with a verified no-guess board and clear opening. */
-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 candidate-board budget for verified generation. */
+/** 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;

package/dist/jirai.types.d.ts

@@ -1,5 +1,9 @@
 /** 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. */
@@ -29,6 +33,7 @@ export type Board = {
     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. */
@@ -65,9 +70,15 @@ 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. */
+/**
+ * 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. */

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/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;