@johnmorrisdotca/jirai 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,20 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-05
+
+- **Huge fields.** `hugeSettings(level, { grid, shape, size })` and `HUGE_SIZES` (32×32, 48×24 and 24×48) give each of the four levels on a field of four times the medium level's area, 1,024 to 1,152 squares, with the level's share of mines (a 32×32 has 126, 160, 211 and 256 mines at easy, medium, hard and extra-hard), on every rule set and outline. Every one is dealt and proved to need no guess in a median of 3 to 60 ms (73 ms the slowest of ten 32×32 seeds), on the square, orthogonal, hexagonal and wraparound grids and the heart, star and hexagon outlines, and `src/huge.test.ts` wins a 32×32 at easy and at extra-hard by the explained hints alone. The demo's Level menu offers them (`?level=huge-hard`).
+- **A faster hint.** `deduce` compares a count only with the counts that hold its first square, and `hintFor` builds the neighbours once instead of at every step: on a 32×32 extra-hard field the explained hint took 51 ms on average and up to 400 ms late in the game, now 8 ms and at most 43 ms. The hints it finds are the same ones.
+- Measured, not changed: a reveal or a flag on a 1,024-square board is 4 ms of script, 20 ms with the processor slowed fourfold, and the next frame follows (2,400 squares, the most settings accept: 36 ms), so the board stays plain buttons; the README has the numbers.
+
+## [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,49 @@ 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).
+
+### Huge fields
+
+`hugeSettings(level, { grid, shape, size })` is the same four levels on a field of four times the area of the medium one: 32×32 (1,024 squares), or 48×24 or 24×48 (1,152; `HUGE_SIZES` lists them) with the level's own share of the mines, so a 32×32 has 126 mines at `easy`, 160 at `medium`, 211 at `hard` and 256 at `extra-hard`, and a heart, star or hexagon outline keeps the share over the squares it has left. They are the same fields as any other: seeded, a safe opening, and every one proved to need no guess, on all four rule sets and all four outlines (`src/huge.test.ts`, and the winning of 32×32 fields at easy and extra-hard by the explained hints alone).
+
+Measured on a Mac (20 cores, busy): dealing and proving a 32×32 takes a median of 3 ms at easy, 5 ms at medium, 11 ms at hard and 60 ms at extra-hard (the slowest of ten seeds 73 ms; 48×24 at extra-hard 54 ms median, 91 ms slowest); the orthogonal four-neighbour field, the hardest to finish, took 46 ms median and 87 ms slowest at 25%. The player deals in a worker, so the page is never held. A reveal or a flag on the 1,024-square board is answered in 4 ms of script on the desk and about 20 ms with the processor slowed fourfold, as a phone's is, and the next frame follows at once (36 ms with 2,400 squares, the most a field may have), so the board is plain buttons still and needs no canvas. The explained `hintFor` takes 8 ms on average and at most 43 ms late in a 32×32 extra-hard field (it was 51 and 400 before 0.4.0).
+
+```ts
+import { DEFAULT_SETTINGS, hugeSettings, newGame } from "@johnmorrisdotca/jirai";
+
+const game = newGame({ ...DEFAULT_SETTINGS, ...hugeSettings("hard"), seed: 7 }); // 32 × 32, 211 mines
+```
+
+```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 +161,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/deduce.d.ts

@@ -3,6 +3,6 @@ import type { Deduction, VisibleGame } from "./jirai.types.ts";
  * What the clues prove, without reading the answer or trusting a player's
  * flags. A flag is a note; treating it as evidence makes a bad note a bad hint.
  */
-export declare function deduce(game: VisibleGame, knownMines?: ReadonlySet<number>, enumerate?: boolean): Deduction;
+export declare function deduce(game: VisibleGame, knownMines?: ReadonlySet<number>, enumerate?: boolean, adjacent?: readonly (readonly number[])[]): Deduction;
 /** Keep discovering certain mines until there is a safe cell or nothing more is proved. */
 export declare function hintFor(game: VisibleGame): Deduction;

package/dist/deduce.js

@@ -4,8 +4,7 @@ import { neighboursOf } from "./grid.js";
  * What the clues prove, without reading the answer or trusting a player's
  * flags. A flag is a note; treating it as evidence makes a bad note a bad hint.
  */
-export function deduce(game, knownMines = new Set(), enumerate = true) {
-    const adjacent = neighboursOf(game.settings);
+export function deduce(game, knownMines = new Set(), enumerate = true, adjacent = neighboursOf(game.settings)) {
     const constraints = [];
     const empty = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
     for (let cell = 0; cell < game.clues.length; cell += 1) {
@@ -43,10 +42,21 @@ export function deduce(game, knownMines = new Set(), enumerate = true) {
     }
     // Compare a smaller clue with a larger one, including the mine counter.
     // Their difference is another exact count. Never subtract mere overlaps.
-    const sets = [...constraints, total].map((c) => new Set(c.cells));
     const all = [...constraints, total];
-    for (let i = 0; i < all.length; i += 1)
-        for (let j = 0; j < all.length; j += 1) {
+    const sets = all.map((c) => new Set(c.cells));
+    // A constraint can only be inside another that holds its first cell, so each is compared with those alone, in the same order as
+    // comparing it with every other. On a large field that is a handful of neighbours instead of every clue on the board.
+    const holding = new Map();
+    all.forEach((c, index) => { for (const cell of c.cells) {
+        const list = holding.get(cell);
+        if (list === undefined)
+            holding.set(cell, [index]);
+        else
+            list.push(index);
+    } });
+    for (let i = 0; i < all.length; i += 1) {
+        const inside = all[i].cells.length === 0 ? all.map((_, index) => index) : holding.get(all[i].cells[0]);
+        for (const j of inside) {
             if (i === j || all[i].cells.length >= all[j].cells.length)
                 continue;
             if (!all[i].cells.every((cell) => sets[j].has(cell)))
@@ -62,6 +72,7 @@ export function deduce(game, knownMines = new Set(), enumerate = true) {
             if (result !== null)
                 return result;
         }
+    }
     // A whole-board constraint would join otherwise independent components.
     // Local enumeration is conservative; the global counter is used above.
     return enumerate ? enumerateForced(constraints) : empty;
@@ -69,9 +80,10 @@ export function deduce(game, knownMines = new Set(), enumerate = true) {
 /** Keep discovering certain mines until there is a safe cell or nothing more is proved. */
 export function hintFor(game) {
     const known = new Set();
+    const adjacent = neighboursOf(game.settings);
     let last = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
     while (known.size <= game.settings.mines) {
-        const result = deduce(game, known);
+        const result = deduce(game, known, true, adjacent);
         if (result.contradiction || result.safe.length)
             return result;
         const fresh = result.mines.filter((cell) => !known.has(cell));

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.4.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 { hugeSettings, levelNamed, levelSettings } from "./levels.ts";
+export type { HugeSize, 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.4.0";
 export { SHAPES, activeCell, activeCells } from "./shape.js";
 export * from "./orthogonal.js";
+export { measureBoard } from "./measure.js";
+export { hugeSettings, levelNamed, levelSettings } from "./levels.js";

package/dist/jirai.constants.d.ts

@@ -31,22 +31,51 @@ 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;
+}>;
+/**
+ * The huge fields: four times the area of a 16×16 (the medium level), 1,024 to 1,152 squares, for a long solve. The same
+ * share of mines as a level, see `hugeSettings`. They are dealt, proved and drawn like any other field: a no-guess deal takes
+ * a few milliseconds to a tenth of a second here, and 2,400 squares is the most `validSettings` accepts.
+ */
+export declare const HUGE_SIZES: readonly [{
+    readonly width: 32;
+    readonly height: 32;
+}, {
+    readonly width: 48;
+    readonly height: 24;
+}, {
+    readonly width: 24;
+    readonly height: 48;
+}];
+/** 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 +87,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,39 @@ 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 },
+};
+/**
+ * The huge fields: four times the area of a 16×16 (the medium level), 1,024 to 1,152 squares, for a long solve. The same
+ * share of mines as a level, see `hugeSettings`. They are dealt, proved and drawn like any other field: a no-guess deal takes
+ * a few milliseconds to a tenth of a second here, and 2,400 squares is the most `validSettings` accepts.
+ */
+export const HUGE_SIZES = [{ width: 32, height: 32 }, { width: 48, height: 24 }, { width: 24, height: 48 }];
+/** 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,32 @@
+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;
+/** The outline of a huge field: one of `HUGE_SIZES`' width and height. */
+export type HugeSize = {
+    width: number;
+    height: number;
+};
+/**
+ * The size and mine count of a level on a huge field: a field of `HUGE_SIZES` (32 × 32 unless `size` says another of them),
+ * with the level's own share of mines over its squares. Easy is 12% mines, medium 16%, hard 21% and extra-hard 25%, as
+ * on the level's own field, and a heart, star or hexagon outline keeps that share over the squares it has left. Every
+ * field is still dealt and proved to need no guess, on every grid. Throws `RangeError` for a name that is no level or a size that is not huge.
+ */
+export declare function hugeSettings(level: Level | LevelAlias, board?: {
+    grid?: Grid;
+    shape?: Settings["shape"];
+    size?: HugeSize;
+}): LevelSize;

package/dist/levels.js

@@ -0,0 +1,47 @@
+import { HUGE_SIZES, 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))) };
+}
+/**
+ * The size and mine count of a level on a huge field: a field of `HUGE_SIZES` (32 × 32 unless `size` says another of them),
+ * with the level's own share of mines over its squares. Easy is 12% mines, medium 16%, hard 21% and extra-hard 25%, as
+ * on the level's own field, and a heart, star or hexagon outline keeps that share over the squares it has left. Every
+ * field is still dealt and proved to need no guess, on every grid. Throws `RangeError` for a name that is no level or a size that is not huge.
+ */
+export function hugeSettings(level, board = {}) {
+    const named = levelNamed(level);
+    if (named === null)
+        throw new RangeError(`Unknown level: ${String(level)}`);
+    const size = board.size ?? HUGE_SIZES[0];
+    if (!HUGE_SIZES.some((huge) => huge.width === size.width && huge.height === size.height))
+        throw new RangeError(`Not a huge size: ${size.width} × ${size.height}`);
+    const own = LEVEL_SIZES[named];
+    const probe = { width: size.width, height: size.height, mines: 1, 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(own.mines / (own.width * own.height) * cells))) };
+}