@johnmorrisdotca/jirai 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,12 @@ 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.

package/README.md

@@ -116,6 +116,18 @@ The optional React entry exports `JiraiBoard` from `@johnmorrisdotca/jirai/react
 
 `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";
 

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/index.d.ts

@@ -8,11 +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.3.0";
+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 { levelNamed, levelSettings } from "./levels.ts";
-export type { LevelSize } from "./levels.ts";
+export { hugeSettings, levelNamed, levelSettings } from "./levels.ts";
+export type { HugeSize, LevelSize } from "./levels.ts";

package/dist/index.js

@@ -8,8 +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.3.0";
+export const VERSION = "0.4.0";
 export { SHAPES, activeCell, activeCells } from "./shape.js";
 export * from "./orthogonal.js";
 export { measureBoard } from "./measure.js";
-export { levelNamed, levelSettings } from "./levels.js";
+export { hugeSettings, levelNamed, levelSettings } from "./levels.js";

package/dist/jirai.constants.d.ts

@@ -45,6 +45,21 @@ export declare const LEVEL_SIZES: Record<(typeof LEVELS)[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: {

package/dist/jirai.constants.js

@@ -24,6 +24,12 @@ export const LEVEL_SIZES = {
     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 = {
     ...LEVEL_SIZES,

package/dist/levels.d.ts

@@ -14,3 +14,19 @@ 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

@@ -1,4 +1,4 @@
-import { LEVEL_ALIASES, LEVEL_SIZES, LEVELS } from "./jirai.constants.js";
+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`,
@@ -27,3 +27,21 @@ export function levelSettings(level, board = {}) {
     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))) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/jirai",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Minesweeper on square, orthogonal, hexagonal and wraparound boards: four levels up to extra-hard, seeded games, a safe opening, verified no-guess boards, explained hints, configurable materials and markers, and a playable board for any page. Zero runtime dependencies.",
   "type": "module",
   "license": "MIT",

package/src/deduce.ts

@@ -6,8 +6,7 @@ import type { Constraint, 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 function deduce(game: VisibleGame, knownMines: ReadonlySet<number> = new Set(), enumerate = true): Deduction {
-  const adjacent = neighboursOf(game.settings);
+export function deduce(game: VisibleGame, knownMines: ReadonlySet<number> = new Set(), enumerate = true, adjacent: readonly (readonly number[])[] = neighboursOf(game.settings)): Deduction {
   const constraints: Constraint[] = [];
   const empty: Deduction = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
   for (let cell = 0; cell < game.clues.length; cell += 1) {
@@ -31,19 +30,26 @@ export function deduce(game: VisibleGame, knownMines: ReadonlySet<number> = new
   if (unknown.length) { const result = forced(total, "total"); if (result !== null) return result; }
   // Compare a smaller clue with a larger one, including the mine counter.
   // Their difference is another exact count. Never subtract mere overlaps.
-  const sets = [...constraints, total].map((c) => new Set(c.cells));
   const all = [...constraints, total];
-  for (let i = 0; i < all.length; i += 1) for (let j = 0; j < all.length; j += 1) {
-    if (i === j || all[i]!.cells.length >= all[j]!.cells.length) continue;
-    if (!all[i]!.cells.every((cell) => sets[j]!.has(cell))) continue;
-    const c: Constraint = {
-      cells: all[j]!.cells.filter((cell) => !sets[i]!.has(cell)),
-      mines: all[j]!.mines - all[i]!.mines,
-      sources: [...new Set([...all[i]!.sources, ...all[j]!.sources])],
-    };
-    if (c.mines < 0 || c.mines > c.cells.length) return { ...empty, contradiction: true };
-    const result = forced(c, j === all.length - 1 ? "total" : "overlap");
-    if (result !== null) return result;
+  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<number, number[]>();
+  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))) continue;
+      const c: Constraint = {
+        cells: all[j]!.cells.filter((cell) => !sets[i]!.has(cell)),
+        mines: all[j]!.mines - all[i]!.mines,
+        sources: [...new Set([...all[i]!.sources, ...all[j]!.sources])],
+      };
+      if (c.mines < 0 || c.mines > c.cells.length) return { ...empty, contradiction: true };
+      const result = forced(c, j === all.length - 1 ? "total" : "overlap");
+      if (result !== null) return result;
+    }
   }
   // A whole-board constraint would join otherwise independent components.
   // Local enumeration is conservative; the global counter is used above.
@@ -53,9 +59,10 @@ export function deduce(game: VisibleGame, knownMines: ReadonlySet<number> = new
 /** Keep discovering certain mines until there is a safe cell or nothing more is proved. */
 export function hintFor(game: VisibleGame): Deduction {
   const known = new Set<number>();
+  const adjacent = neighboursOf(game.settings);
   let last: Deduction = { 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));
     if (!fresh.length) return last;

package/src/index.ts

@@ -8,7 +8,7 @@ export * from "./deduce.ts";
 export * from "./keep.ts";
 export { seededRandom } from "./random.ts";
 /** Package version, kept in step with the release metadata. */
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.0";
 
 export { SHAPES, activeCell, activeCells } from "./shape.ts";
 
@@ -16,5 +16,5 @@ 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";
+export { hugeSettings, levelNamed, levelSettings } from "./levels.ts";
+export type { HugeSize, LevelSize } from "./levels.ts";

package/src/jirai.constants.ts

@@ -26,6 +26,12 @@ export const LEVEL_SIZES: Record<(typeof LEVELS)[number], { width: number; heigh
   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 }] as const satisfies readonly { width: number; height: number }[];
 /** Common minefield dimensions and mine counts. The levels, their older names, and two shapes of field. */
 export const PRESETS = {
   ...LEVEL_SIZES,

package/src/levels.ts

@@ -1,4 +1,4 @@
-import { LEVEL_ALIASES, LEVEL_SIZES, LEVELS } from "./jirai.constants.ts";
+import { HUGE_SIZES, LEVEL_ALIASES, LEVEL_SIZES, LEVELS } from "./jirai.constants.ts";
 import { activeCells } from "./shape.ts";
 import type { Grid, Level, LevelAlias, Settings } from "./jirai.types.ts";
 
@@ -29,3 +29,23 @@ export function levelSettings(level: Level | LevelAlias, board: { grid?: Grid; s
   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 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 function hugeSettings(level: Level | LevelAlias, board: { grid?: Grid; shape?: Settings["shape"]; size?: HugeSize } = {}): LevelSize {
+  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 } as const;
+  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))) };
+}