@johnmorrisdotca/jirai 0.0.0-stage → 0.1.0

package/src/game.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from "vitest";
+import { newGame, play, visibleGame } from "./game.ts";
+import { makeBoard, isSolvable, GenerationError } from "./generate.ts";
+import { DEFAULT_SETTINGS, GRIDS, MARKS, MOVES, STATUSES } from "./jirai.constants.ts";
+import { neighbours, neighboursOf, validSettings } from "./grid.ts";
+import { gameFromProgress, gameProgress, dailySeed } from "./keep.ts";
+import { boardModel } from "./draw.ts";
+import type { Board, Game, Settings } from "./jirai.types.ts";
+
+function fixedGame(minesAt: number[]): Game {
+  const settings: Settings = { ...DEFAULT_SETTINGS, width: 5, height: 5, mines: minesAt.length, noGuess: false, opening: "safe" };
+  const mines = Array.from({ length: 25 }, (_, cell) => minesAt.includes(cell));
+  const clues = mines.map((mine, cell) => mine ? -1 : neighbours(settings, cell).filter((n) => mines[n]).length);
+  const board: Board = { settings, mines, clues, first: 12, attempt: 0 };
+  return { ...newGame(settings), board };
+}
+
+describe("the three boards", () => {
+  for (const grid of Object.values(GRIDS)) it(`${grid} has reciprocal, unique neighbours and no self-neighbours`, () => {
+    const settings = { ...DEFAULT_SETTINGS, width: 7, height: 5, grid };
+    const all = neighboursOf(settings);
+    for (let cell = 0; cell < all.length; cell += 1) {
+      expect(new Set(all[cell]).size).toBe(all[cell]!.length);
+      expect(all[cell]).not.toContain(cell);
+      for (const n of all[cell]!) expect(all[n]).toContain(cell);
+    }
+  });
+  it("uses six hex neighbours, eight square neighbours, and joins both wrap seams", () => {
+    expect(neighbours({ ...DEFAULT_SETTINGS, grid: GRIDS.hex }, 40)).toHaveLength(6);
+    expect(neighbours(DEFAULT_SETTINGS, 40)).toHaveLength(8);
+    expect(neighbours({ ...DEFAULT_SETTINGS, grid: GRIDS.wrap }, 0)).toEqual([1,8,9,10,17,72,73,80]);
+  });
+  it("rejects malformed or excessive settings before making a board", () => {
+    for (const change of [{ width: 1 }, { width: 61 }, { width: 60, height: 60 }, { mines: 81 }, { seed: NaN }, { grid: "__proto__" }, { mines: 1.5 }, { noGuess: "yes" }]) expect(validSettings({ ...DEFAULT_SETTINGS, ...change })).toBe(false);
+  });
+});
+
+describe("dealing and verified boards", () => {
+  for (const grid of Object.values(GRIDS)) it(`${grid} deals exact counts and a clear first opening for many seeds`, () => {
+    for (let seed = 0; seed < 40; seed += 1) {
+      const settings = { ...DEFAULT_SETTINGS, grid, seed, noGuess: false };
+      const board = makeBoard(settings, 40);
+      expect(board.mines.filter(Boolean)).toHaveLength(10);
+      expect(board.clues[40]).toBe(0);
+      for (let cell = 0; cell < 81; cell += 1) {
+        expect(board.clues[cell]).toBe(board.mines[cell] ? -1 : neighbours(settings, cell).filter((n) => board.mines[n]).length);
+      }
+      expect(makeBoard(settings, 40)).toEqual(board);
+    }
+  });
+  for (const grid of Object.values(GRIDS)) it(`${grid} only advertises boards its visible-clue solver actually finishes`, () => {
+    for (let seed = 0; seed < 15; seed += 1) expect(isSolvable(makeBoard({ ...DEFAULT_SETTINGS, grid, seed }, 40))).toBe(true);
+  });
+  it("reports a failed proof budget rather than returning an unverified board", () => {
+    let failures = 0;
+    for (let seed = 0; seed < 50; seed += 1) {
+      try { makeBoard({ ...DEFAULT_SETTINGS, width: 5, height: 5, mines: 10, opening: "safe", seed }, 12, { attempts: 1 }); }
+      catch (error) { expect(error).toBeInstanceOf(GenerationError); expect((error as GenerationError).code).toBe("exhausted"); failures += 1; }
+    }
+    expect(failures).toBeGreaterThan(0);
+  });
+  it("rejects a dense board that cannot protect the chosen opening", () => {
+    expect(() => makeBoard({ ...DEFAULT_SETTINGS, width: 3, height: 3, mines: 1 }, 4)).toThrow(GenerationError);
+  });
+});
+
+describe("moves", () => {
+  it("floods empty ground and wins without requiring any flags", () => {
+    const game = fixedGame([0]);
+    const before = structuredClone(game);
+    const next = play(game, { kind: MOVES.reveal, cell: 24 });
+    expect(next.status).toBe(STATUSES.won);
+    expect(next.marks.filter((mark) => mark === MARKS.open)).toHaveLength(24);
+    expect(game).toEqual(before);
+  });
+  it("does not open a flagged cell, including inside a flood", () => {
+    let game = fixedGame([0]);
+    game = play(game, { kind: MOVES.mark, cell: 24 });
+    expect(play(game, { kind: MOVES.reveal, cell: 24 })).toBe(game);
+    game = play(game, { kind: MOVES.reveal, cell: 20 });
+    expect(game.marks[24]).toBe(MARKS.flag);
+    expect(game.status).toBe(STATUSES.playing);
+  });
+  it("cycles notes through flag, question and covered", () => {
+    let game = newGame();
+    for (const mark of [MARKS.flag, MARKS.question, MARKS.covered]) { game = play(game, { kind: MOVES.mark, cell: 0 }); expect(game.marks[0]).toBe(mark); }
+    expect(game.board).toBeNull();
+  });
+  it("chords a matched number and loses if the flags were wrong", () => {
+    let game = fixedGame([0,24]);
+    game = play(game, { kind: MOVES.reveal, cell: 6 });
+    expect(play(game, { kind: MOVES.chord, cell: 6 })).toBe(game);
+    game = play(game, { kind: MOVES.mark, cell: 1 });
+    game = play(game, { kind: MOVES.chord, cell: 6 });
+    expect(game.status).toBe(STATUSES.lost); expect(game.exploded).toBe(0);
+    expect(play(game, { kind: MOVES.mark, cell: 3 })).toBe(game);
+  });
+  it("chords correctly flagged mines without revealing them", () => {
+    let game = fixedGame([0,24]);
+    game = play(game, { kind: MOVES.reveal, cell: 6 });
+    game = play(game, { kind: MOVES.mark, cell: 0 });
+    game = play(game, { kind: MOVES.chord, cell: 6 });
+    expect(game.status).not.toBe(STATUSES.lost); expect(game.marks[0]).toBe(MARKS.flag);
+  });
+  it("keeps hidden answers out of both the clue view and drawing", () => {
+    const game = fixedGame([0,24]);
+    expect(visibleGame(game).clues.every((clue) => clue === null)).toBe(true);
+    expect(boardModel(game).cells.every((cell) => cell.text === "" && cell.kind === MARKS.covered)).toBe(true);
+  });
+  it("replays a saved game from its seed and moves; malformed records are refused", () => {
+    let game = newGame({ ...DEFAULT_SETTINGS, noGuess: false });
+    game = play(game, { kind: MOVES.mark, cell: 0 }); game = play(game, { kind: MOVES.reveal, cell: 40 });
+    expect(gameFromProgress(gameProgress(game))).toEqual(game);
+    for (const data of ["garbage", "null", '{"version":2}', JSON.stringify({ version: 1, settings: DEFAULT_SETTINGS, moves: [{ kind: "reveal", cell: -1 }] })]) expect(gameFromProgress(data)).toBeNull();
+  });
+  it("has stable daily seeds and rejects impossible calendar dates", () => {
+    expect(dailySeed("2026-10-04")).toBe(dailySeed("2026-10-04"));
+    expect(dailySeed("2026-10-04", "hex")).not.toBe(dailySeed("2026-10-04"));
+    expect(() => dailySeed("2026-02-30")).toThrow();
+  });
+});
+
+export { fixedGame };
+
+it("keeps assisted status through public progress and rejects invalid assisted data", () => {
+  const game = { ...newGame(), helped: true };
+  expect(gameFromProgress(gameProgress(game))?.helped).toBe(true);
+  expect(gameFromProgress(JSON.stringify({ version: 1, settings: game.settings, moves: [], helped: "yes" }))).toBeNull();
+});

package/src/game.ts

@@ -0,0 +1,55 @@
+import { activeCell, activeCells } from "./shape.ts";
+import { flood } from "./flood.ts";
+import { makeBoard } from "./generate.ts";
+import { DEFAULT_SETTINGS, MARKS, MOVES, STATUSES } from "./jirai.constants.ts";
+import { neighbours, neighboursOf, validCell, validSettings } from "./grid.ts";
+import type { Board, Game, Move, Settings, VisibleGame } from "./jirai.types.ts";
+
+export function newGame(settings: Settings = DEFAULT_SETTINGS): Game {
+  if (!validSettings(settings)) throw new RangeError("Invalid Minesweeper settings.");
+  return { settings: { ...settings }, board: null, marks: Array.from({ length: settings.width * settings.height }, () => MARKS.covered), status: STATUSES.ready, exploded: null, moves: [], helped: false };
+}
+
+/** The clue-only view used by the solver. No hidden mine, including under a flag, survives it. */
+export function visibleGame(game: Game): VisibleGame {
+  return { settings: { ...game.settings }, marks: [...game.marks], status: game.status,
+    clues: game.marks.map((mark, cell) => !activeCell(game.settings, cell) ? -2 : mark === MARKS.open ? game.board?.clues[cell] ?? null : null) };
+}
+
+/** Accept a worker's dealt board without changing any moves made before the opening. */
+export function withBoard(game: Game, board: Board): Game {
+  if (game.board !== null || (game.settings.shape ?? "rectangle") !== (board.settings.shape ?? "rectangle") || (Object.keys(DEFAULT_SETTINGS) as (keyof Settings)[]).some(key => game.settings[key] !== board.settings[key])) throw new Error("The board does not belong to this game.");
+  return { ...game, board };
+}
+
+/** A legal move returns a new game; an unavailable move returns the same one. */
+export function play(game: Game, move: Move): Game {
+  if (!validCell(game.settings, move.cell) || game.status === STATUSES.won || game.status === STATUSES.lost) return game;
+  const before = game.marks[move.cell]!;
+  if (move.kind === MOVES.mark) {
+    if (before === MARKS.open) return game;
+    const marks = [...game.marks];
+    marks[move.cell] = before === MARKS.covered ? MARKS.flag : before === MARKS.flag ? MARKS.question : MARKS.covered;
+    return { ...game, marks, moves: [...game.moves, { ...move }] };
+  }
+  if (move.kind !== MOVES.reveal && move.kind !== MOVES.chord) return game;
+  if (before === MARKS.flag || (move.kind === MOVES.chord && before !== MARKS.open)) return game;
+  const board = game.board ?? makeBoard(game.settings, move.cell);
+  let starts = [move.cell];
+  if (before === MARKS.open) {
+    const around = neighbours(game.settings, move.cell);
+    if (around.filter((cell) => game.marks[cell] === MARKS.flag).length !== board.clues[move.cell]) return game;
+    starts = around.filter((cell) => game.marks[cell] !== MARKS.flag && game.marks[cell] !== MARKS.open);
+  }
+  if (!starts.length) return game;
+  const marks = [...game.marks];
+  const exploded = starts.find((cell) => board.mines[cell]) ?? null;
+  const open = marks.map((mark) => mark === MARKS.open);
+  const blocked = new Set(marks.flatMap((mark, cell) => mark === MARKS.flag ? [cell] : []));
+  flood(board.clues, neighboursOf(game.settings), open, starts, blocked);
+  for (let cell = 0; cell < marks.length; cell += 1) if (open[cell]) marks[cell] = MARKS.open;
+  if (exploded !== null) marks[exploded] = MARKS.open;
+  const status = exploded !== null ? STATUSES.lost
+    : open.filter(Boolean).length === activeCells(game.settings).length - game.settings.mines ? STATUSES.won : STATUSES.playing;
+  return { ...game, board, marks, status, exploded, moves: [...game.moves, { ...move }] };
+}

package/src/generate.ts

@@ -0,0 +1,57 @@
+import { activeCell, activeCells } from "./shape.ts";
+import { deduce } from "./deduce.ts";
+import { flood } from "./flood.ts";
+import { GENERATION_ATTEMPTS, MARKS, STATUSES } from "./jirai.constants.ts";
+import { neighbours, neighboursOf, validCell, validSettings } from "./grid.ts";
+import { seededRandom, shuffled } from "./random.ts";
+import type { Board, GenerationOptions, Settings, VisibleGame } from "./jirai.types.ts";
+
+/** A bounded generator must say it failed, never quietly return a guessing board. */
+export class GenerationError extends Error {
+  constructor(public readonly code: "settings" | "opening" | "exhausted", message: string) { super(message); this.name = "GenerationError"; }
+}
+
+/** Verify a board from one opening, using only clues that have been uncovered. */
+export function isSolvable(board: Board, enumerate = true): boolean {
+  const adjacent = neighboursOf(board.settings);
+  const open = board.clues.map(() => false);
+  const known = new Set<number>();
+  flood(board.clues, adjacent, open, [board.first]);
+  while (open.filter(Boolean).length < activeCells(board.settings).length - board.settings.mines) {
+    const visible: VisibleGame = {
+      settings: board.settings, clues: board.clues.map((n, cell) => activeCell(board.settings, cell) ? open[cell] ? n : null : -2),
+      marks: open.map((yes) => yes ? MARKS.open : MARKS.covered), status: STATUSES.playing,
+    };
+    const result = deduce(visible, known, enumerate);
+    if (result.contradiction) return false;
+    let changed = false;
+    for (const cell of result.mines) {
+      if (!board.mines[cell]) return false;
+      if (!known.has(cell)) { known.add(cell); changed = true; }
+    }
+    if (result.safe.some((cell) => board.mines[cell])) return false;
+    if (result.safe.some((cell) => !open[cell])) { flood(board.clues, adjacent, open, result.safe); changed = true; }
+    if (!changed) return false;
+  }
+  return true;
+}
+
+/** Deal after the first reveal. A seed fixes the whole candidate stream and the accepted board. */
+export function makeBoard(settings: Settings, first: number, options: GenerationOptions = {}): Board {
+  if (!validSettings(settings) || !validCell(settings, first)) throw new GenerationError("settings", "Invalid board settings or opening cell.");
+  const protectedCells = new Set([first, ...(settings.opening === "clear" ? neighbours(settings, first) : [])]);
+  const available = Array.from({ length: settings.width * settings.height }, (_, cell) => cell).filter((cell) => validCell(settings, cell) && !protectedCells.has(cell));
+  if (available.length < settings.mines) throw new GenerationError("opening", "Too many mines for a safe opening at this 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 random = seededRandom(settings.seed);
+  const adjacent = neighboursOf(settings);
+  for (let attempt = 0; attempt < (settings.noGuess ? attempts : 1); attempt += 1) {
+    const places = new Set(shuffled(available, random).slice(0, settings.mines));
+    const mines = available.length ? Array.from({ length: settings.width * settings.height }, (_, cell) => places.has(cell)) : [];
+    const clues = mines.map((mine, cell) => !activeCell(settings, cell) ? -2 : mine ? -1 : adjacent[cell]!.filter((n) => mines[n]).length);
+    const board: Board = { settings: { ...settings }, mines, clues, first, attempt };
+    if (!settings.noGuess || isSolvable(board, options.enumerate ?? true)) return board;
+  }
+  throw new GenerationError("exhausted", "No verified board found within the work budget. Try another seed, fewer mines, or a different opening.");
+}

package/src/grid.ts

@@ -0,0 +1,42 @@
+import { GRID_SPECS, MAX_CELLS, MAX_SIDE } from "./jirai.constants.ts";
+import { activeCell, activeCells, SHAPES } from "./shape.ts";
+import type { Settings } from "./jirai.types.ts";
+
+/** Reject a setting before it reaches a board allocation or a shuffle. */
+export function validSettings(value: unknown): value is Settings {
+  if (value === null || typeof value !== "object") return false;
+  const s = value as Settings;
+  return Number.isInteger(s.width) && s.width >= 3 && s.width <= MAX_SIDE
+    && Number.isInteger(s.height) && s.height >= 3 && s.height <= MAX_SIDE
+    && s.width * s.height <= MAX_CELLS
+    && Number.isInteger(s.mines) && s.mines >= 1 && s.mines < s.width * s.height
+    && (s.shape === undefined || SHAPES.includes(s.shape))
+    && ((s.shape ?? "rectangle") === "rectangle" || (s.width >= 9 && s.height >= 9 && s.grid !== "wrap"))
+    && s.mines < activeCells(s).length
+    && Object.hasOwn(GRID_SPECS, s.grid) && typeof s.noGuess === "boolean"
+    && (s.opening === "safe" || s.opening === "clear")
+    && Number.isInteger(s.seed) && s.seed >= 0 && s.seed <= 0xffffffff;
+}
+export function validCell(settings: Settings, cell: number): boolean {
+  return Number.isInteger(cell) && cell >= 0 && cell < settings.width * settings.height && activeCell(settings, cell);
+}
+/** Every neighbour once. Wrap joins both pairs of opposite edges. */
+export function neighbours(settings: Settings, cell: number): number[] {
+  if (!validCell(settings, cell)) return [];
+  const spec = GRID_SPECS[settings.grid];
+  const x = cell % settings.width;
+  const y = Math.floor(cell / settings.width);
+  const out = new Set<number>();
+  for (const [dx, dy] of spec.offsets) {
+    let nx = x + dx, ny = y + dy;
+    if (spec.wrap) {
+      nx = (nx + settings.width) % settings.width;
+      ny = (ny + settings.height) % settings.height;
+    }
+    if (nx >= 0 && nx < settings.width && ny >= 0 && ny < settings.height) { const next = ny * settings.width + nx; if (validCell(settings, next)) out.add(next); }
+  }
+  return [...out].sort((a, b) => a - b);
+}
+export function neighboursOf(settings: Settings): number[][] {
+  return Array.from({ length: settings.width * settings.height }, (_, cell) => neighbours(settings, cell));
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/** Jirai 地雷: the rules and deductions, plain functions over plain data. No DOM and no dependencies. */
+export * from "./jirai.types.ts";
+export * from "./jirai.constants.ts";
+export * from "./grid.ts";
+export * from "./generate.ts";
+export * from "./game.ts";
+export * from "./deduce.ts";
+export * from "./keep.ts";
+export { seededRandom } from "./random.ts";
+export const VERSION = "0.1.0";
+
+export { SHAPES, activeCell, activeCells } from "./shape.ts";

package/src/jirai.constants.ts

@@ -0,0 +1,25 @@
+import type { Grid, Settings } from "./jirai.types.ts";
+
+export const GRIDS = { square: "square", hex: "hex", wrap: "wrap" } as const;
+export const STATUSES = { ready: "ready", playing: "playing", won: "won", lost: "lost" } as const;
+export const MARKS = { covered: "covered", flag: "flag", question: "question", open: "open" } as const;
+export const MOVES = { reveal: "reveal", mark: "mark", chord: "chord" } as const;
+/** Hex coordinates are axial: a row is displaced half a cell to the right. */
+export const GRID_SPECS: Record<Grid, { offsets: readonly (readonly [number, number])[]; wrap: boolean }> = {
+  square: { offsets: [[-1,-1],[0,-1],[1,-1],[-1,0],[1,0],[-1,1],[0,1],[1,1]], wrap: false },
+  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 },
+};
+export const PRESETS = {
+  beginner: { width: 9, height: 9, mines: 10 },
+  intermediate: { width: 16, height: 16, mines: 40 },
+  expert: { width: 30, height: 16, mines: 99 },
+  wide: { width: 21, height: 9, mines: 24 },
+  tall: { width: 9, height: 21, mines: 24 },
+} as const;
+export const DEFAULT_SETTINGS: Settings = { ...PRESETS.beginner, grid: GRIDS.square, noGuess: true, opening: "clear", seed: 1 };
+export const MAX_SIDE = 60;
+export const MAX_CELLS = 2400;
+export const GENERATION_ATTEMPTS = 128;
+export const ENUMERATION_CELLS = 18;
+export const ENUMERATION_NODES = 100_000;

package/src/jirai.types.ts

@@ -0,0 +1,56 @@
+/** A cell's number is its row-major place on the board, starting at zero. */
+export type Grid = "square" | "hex" | "wrap";
+export type Status = "ready" | "playing" | "won" | "lost";
+export type Mark = "covered" | "flag" | "question" | "open";
+export type Settings = {
+  /** Shape omits cells; rectangle is the compatible default. Wrap requires rectangle. */
+  shape?: "rectangle" | "heart" | "star" | "hexagon";
+  width: number;
+  height: number;
+  mines: number;
+  grid: Grid;
+  /** Only accept boards the deduction solver finishes from the opening. */
+  noGuess: boolean;
+  /** The opening and every neighbour are safe, not only the first cell. */
+  opening: "safe" | "clear";
+  seed: number;
+};
+export type Move = { kind: "reveal" | "mark" | "chord"; cell: number };
+export type Board = {
+  settings: Settings;
+  mines: readonly boolean[];
+  clues: readonly number[];
+  first: number;
+  attempt: number;
+};
+/** Rules data includes the answer; never send it to a competitive client. Use visibleGame for hints and drawing. */
+export type Game = {
+  settings: Settings;
+  board: Board | null;
+  marks: readonly Mark[];
+  status: Status;
+  exploded: number | null;
+  moves: readonly Move[];
+  /** A proved hint has been shown during this run. */
+  helped: boolean;
+};
+export type VisibleGame = {
+  settings: Settings;
+  /** Null is hidden, including flags. Only opened cells give a clue. */
+  clues: readonly (number | null)[];
+  marks: readonly Mark[];
+  status: Status;
+};
+export type Constraint = { cells: readonly number[]; mines: number; sources: readonly number[] };
+export type Deduction = {
+  safe: readonly number[];
+  mines: readonly number[];
+  reason: "count" | "overlap" | "total" | "enumeration" | "none";
+  sources: readonly number[];
+  /** A conflicting clue, or a board with no consistent mine placement. */
+  contradiction: boolean;
+};
+export type GenerationOptions = { attempts?: number; enumerate?: boolean };
+export type Language = "en" | "ja";
+export type Material = "ivory" | "wood" | "slate";
+export type Pieces = "flags" | "stones" | "flowers";

package/src/keep.ts

@@ -0,0 +1,34 @@
+import { newGame, play } from "./game.ts";
+import { validSettings } from "./grid.ts";
+import type { Game, Move } from "./jirai.types.ts";
+
+/** Keep settings and moves, never an unchecked answer array. Version the deal before changing it. */
+export function gameProgress(game: Game): string {
+  return JSON.stringify({ version: 1, settings: game.settings, moves: game.moves, helped: game.helped });
+}
+
+/** A saved game is rebuilt under the rules. Malformed or unavailable boards return null. */
+export function gameFromProgress(progress: string): Game | null {
+  if (progress.length > 1_000_000) return null;
+  try {
+    const data = JSON.parse(progress);
+    if (data.version !== 1 || !validSettings(data.settings) || !Array.isArray(data.moves) || data.moves.length > 20_000) return null;
+    if (data.helped !== undefined && typeof data.helped !== "boolean") return null;
+    let game = newGame(data.settings);
+    for (const move of data.moves) {
+      if (move === null || typeof move !== "object" || !["reveal", "mark", "chord"].includes(move.kind) || !Number.isInteger(move.cell)) return null;
+      const next = play(game, move as Move);
+      if (next === game) return null;
+      game = next;
+    }
+    return { ...game, helped: data.helped ?? false };
+  } catch { return null; }
+}
+
+/** UTC by definition, so two people sharing a daily seed get the same board. */
+export function dailySeed(day: string, grid = "square"): number {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(day) || new Date(`${day}T00:00:00Z`).toISOString().slice(0, 10) !== day) throw new RangeError("Use a real day as YYYY-MM-DD.");
+  let hash = 2166136261;
+  for (const letter of `jirai:1:${day}:${grid}`) hash = Math.imul(hash ^ letter.charCodeAt(0), 16777619) >>> 0;
+  return hash;
+}

package/src/mount.ts

@@ -0,0 +1,176 @@
+import { activeCells } from "./shape.ts";
+import { hintFor } from "./deduce.ts";
+import { boardModel } from "./draw.ts";
+import { newGame, play, visibleGame, withBoard } from "./game.ts";
+import { MARKS, MOVES, STATUSES } from "./jirai.constants.ts";
+import { validCell } from "./grid.ts";
+import { gameFromProgress, gameProgress } from "./keep.ts";
+import { JIRAI_STYLE } from "./style.ts";
+import { words } from "./strings.ts";
+import type { Board, Game, Move, Settings } from "./jirai.types.ts";
+import type { DrawOptions, JiraiMount, MountOptions } from "./ui.types.ts";
+
+/**
+ * One playable board in any element. The engine owns the rules, this module
+ * owns presses, focus, the clock and the worker. Destroy removes only its own
+ * root, so two mounted boards never take each other's listeners or children.
+ */
+export function mountJirai(host: HTMLElement, options: MountOptions = {}): JiraiMount {
+  const doc = host.ownerDocument;
+  let draw: DrawOptions = { material: "ivory", pieces: "flags", language: "en", ...options };
+  const game = options.progress === undefined ? newGame(options.settings) : gameFromProgress(options.progress);
+  if (game === null) throw new Error("Invalid saved Minesweeper game.");
+  let current: Game = game;
+  let focus = activeCells(game.settings)[0]!, marking = false, hint: number | null = null;
+  let worker: Worker | null = null, pending = false, disposed = false;
+  let started: number | null = null, elapsed = 0;
+  const root = doc.createElement("div"); root.className = "jr-root";
+  const style = doc.createElement("style"); style.textContent = JIRAI_STYLE;
+  const stats = doc.createElement("div"); stats.className = "jr-stats";
+  const scroll = doc.createElement("div"); scroll.className = "jr-scroll";
+  const board = doc.createElement("div"); board.className = "jr-board"; board.setAttribute("role", "group");
+  const status = doc.createElement("p"); status.className = "jr-status"; status.setAttribute("role", "status");
+  const controls = doc.createElement("div"); controls.className = "jr-controls";
+  const help = doc.createElement("p"); help.className = "jr-help";
+  const dialog = doc.createElement("dialog"); dialog.className = "jr-dialog";
+  const close = doc.createElement("button"); close.className = "jr-button jr-close"; close.type = "button";
+  dialog.append(close);
+  scroll.append(board); root.append(style, stats, scroll, status, controls, help); host.append(root, dialog);
+  let lastOpener: HTMLElement | null = null;
+  const leaveDialog = (): void => { root.append(stats, scroll, status, controls, help); lastOpener?.focus(); };
+  dialog.addEventListener("close", leaveDialog);
+  close.addEventListener("click", () => dialog.close());
+  function stopWorker(): void { worker?.terminate(); worker = null; pending = false; }
+  function clock(): number { return elapsed + (started === null ? 0 : Math.floor((Date.now() - started) / 1000)); }
+  function report(next: Game): void {
+    const before = current.status;
+    current = next; hint = null;
+    if (started === null && current.board !== null && current.status === STATUSES.playing) started = Date.now();
+    if (current.status === STATUSES.won || current.status === STATUSES.lost) { elapsed = clock(); started = null; }
+    const detail = structuredClone(current);
+    host.dispatchEvent(new CustomEvent("jirai-change", { detail })); options.onChange?.(detail);
+    if (before !== current.status && (current.status === STATUSES.won || current.status === STATUSES.lost)) {
+      host.dispatchEvent(new CustomEvent("jirai-finish", { detail })); options.onFinish?.(detail);
+    }
+    render();
+  }
+  function failed(error: Error): void { stopWorker(); render(); status.textContent = words(draw.language).error; options.onError?.(error); }
+  function make(move: Move): void {
+    if (disposed || pending) return;
+    if (move.kind === MOVES.reveal && current.board === null && current.marks[move.cell] !== MARKS.flag && validCell(current.settings, move.cell)) {
+      pending = true; render();
+      try {
+        worker = new Worker(new URL("./worker.js", import.meta.url), { type: "module" });
+        worker.onmessage = (event: MessageEvent<{ board?: Board; error?: string }>) => {
+          if (disposed) return;
+          stopWorker();
+          if (event.data.board === undefined) { failed(new Error(event.data.error ?? "Generation failed.")); return; }
+          try { report(play(withBoard(current, event.data.board), move)); } catch (error) { failed(error as Error); }
+        };
+        worker.onerror = () => failed(new Error("The board worker could not load. Serve the package over HTTP, and allow workers in your content security policy."));
+        worker.postMessage({ settings: current.settings, first: move.cell });
+      } catch (error) { failed(error as Error); }
+      return;
+    }
+    try { const next = play(current, move); if (next !== current) report(next); } catch (error) { failed(error as Error); }
+  }
+  function showHint(): void {
+    if (pending || current.status !== STATUSES.playing) return;
+    const result = hintFor(visibleGame(current));
+    const safe = result.safe.find((cell) => current.marks[cell] !== MARKS.open);
+    const mine = result.mines.find((cell) => current.marks[cell] !== MARKS.flag);
+    const highlighted = safe ?? mine ?? null;
+    if (highlighted !== null && !current.helped) report({ ...current, helped: true });
+    hint = highlighted;
+    render();
+    const say = words(draw.language);
+    status.textContent = hint === null ? say.hintNone : `${safe !== undefined ? say.hintSafe : say.hintMine} ${result.reason === "none" ? "" : say[result.reason]}`;
+  }
+  function renderStats(): void {
+    const say = words(draw.language);
+    const values = [[say.mines, current.settings.mines - current.marks.filter((m) => m === MARKS.flag).length], [say.time, `${Math.floor(clock() / 60)}:${String(clock() % 60).padStart(2,"0")}`], [say.moves, current.moves.length]];
+    stats.replaceChildren(...values.map(([label, value]) => {
+      const part = doc.createElement("span"); part.className = "jr-stat";
+      const name = doc.createElement("small"); name.textContent = String(label);
+      const number = doc.createElement("strong"); number.textContent = String(value);
+      part.append(name, number); return part;
+    }));
+  }
+  function render(): void {
+    if (disposed) return;
+    const say = words(draw.language);
+    root.dataset.material = draw.material; root.dataset.grid = current.settings.grid; root.dataset.shape = current.settings.shape ?? "rectangle"; root.lang = draw.language ?? "en";
+    board.setAttribute("aria-label", say.board); board.setAttribute("aria-busy", String(pending));
+    const model = boardModel(current, { ...draw, hint });
+    const active = doc.activeElement instanceof HTMLElement && board.contains(doc.activeElement);
+    board.style.aspectRatio = `${model.width} / ${model.height}`;
+    board.style.minWidth = `${model.width * 27}px`;
+    board.replaceChildren(...model.cells.map((cell) => {
+      const button = doc.createElement("button"); button.type = "button"; button.className = "jr-cell";
+      button.dataset.cell = String(cell.cell); button.dataset.kind = cell.kind; button.dataset.hint = String(cell.hint);
+      button.dataset.number = cell.kind === MARKS.open ? cell.text : "";
+      button.setAttribute("aria-label", cell.label); button.tabIndex = cell.cell === focus ? 0 : -1;
+      button.disabled = pending; button.textContent = cell.text;
+      button.style.left = `${cell.x / model.width * 100}%`; button.style.top = `${cell.y / model.height * 100}%`;
+      button.style.width = `${cell.width / model.width * 100}%`; button.style.height = `${cell.height / model.height * 100}%`;
+      return button;
+    }));
+    if (active) board.querySelector<HTMLButtonElement>(`[data-cell="${focus}"]`)?.focus({ preventScroll: true });
+    renderStats(); status.textContent = pending ? say.checking : say[current.status]; help.textContent = say.help; close.textContent = say.close;
+    controls.replaceChildren();
+    if (options.controls === false) { stats.hidden = true; status.hidden = true; help.hidden = true; return; }
+    const button = (text: string, action: () => void): HTMLButtonElement => {
+      const made = doc.createElement("button"); made.type = "button"; made.className = "jr-button"; made.textContent = text;
+      made.addEventListener("click", action); controls.append(made); return made;
+    };
+    button(say.restart, () => handle.restart());
+    const mark = button(marking ? say.mark : say.reveal, () => { marking = !marking; render(); }); mark.setAttribute("aria-pressed", String(marking));
+    const hinted = button(say.hint, showHint); hinted.disabled = pending || current.status !== STATUSES.playing;
+    if (!dialog.open) button(say.view, () => { lastOpener = doc.activeElement as HTMLElement; dialog.append(stats, scroll, status, controls); dialog.showModal(); render(); });
+  }
+  function cellOf(event: Event): number | null {
+    const target = event.target instanceof Element ? event.target.closest<HTMLButtonElement>("[data-cell]") : null;
+    return target === null ? null : Number(target.dataset.cell);
+  }
+  let hold: ReturnType<typeof setTimeout> | null = null, held = false, origin = { x: 0, y: 0 };
+  const cancelHold = (): void => { if (hold !== null) clearTimeout(hold); hold = null; };
+  board.addEventListener("pointerdown", (event) => {
+    held = false; cancelHold(); const cell = cellOf(event); if (cell === null) return;
+    focus = cell; origin = { x: event.clientX, y: event.clientY };
+    if (event.pointerType !== "mouse") hold = setTimeout(() => { held = true; make({ kind: MOVES.mark, cell }); }, 450);
+  });
+  board.addEventListener("pointermove", (event) => { if (Math.hypot(event.clientX - origin.x, event.clientY - origin.y) > 8) cancelHold(); });
+  board.addEventListener("pointerup", cancelHold); board.addEventListener("pointercancel", cancelHold);
+  board.addEventListener("click", (event) => { const cell = cellOf(event); if (cell !== null && !held) { focus = cell; make({ kind: marking ? MOVES.mark : MOVES.reveal, cell }); } held = false; });
+  board.addEventListener("contextmenu", (event) => { event.preventDefault(); cancelHold(); const cell = cellOf(event); if (cell !== null && !held) { focus = cell; make({ kind: MOVES.mark, cell }); } held = false; });
+  board.addEventListener("keydown", (event) => {
+    const cell = cellOf(event); if (cell === null) return;
+    const x = cell % current.settings.width, y = Math.floor(cell / current.settings.width);
+    const shifts: Record<string, number> = { ArrowLeft: x > 0 ? -1 : 0, ArrowRight: x < current.settings.width - 1 ? 1 : 0, ArrowUp: y > 0 ? -current.settings.width : 0, ArrowDown: y < current.settings.height - 1 ? current.settings.width : 0 };
+    if (event.key in shifts) { event.preventDefault(); const step = shifts[event.key]!;
+      let next = cell + step;
+      while (step !== 0 && next >= 0 && next < current.marks.length && !validCell(current.settings, next)) {
+        if (Math.abs(step) === 1 && Math.floor(next / current.settings.width) !== y) break;
+        next += step;
+      }
+      if (validCell(current.settings, next) && (Math.abs(step) !== 1 || Math.floor(next / current.settings.width) === y)) focus = next;
+      render(); board.querySelector<HTMLButtonElement>(`[data-cell="${focus}"]`)?.focus(); }
+    else if (event.key === " " || event.key.toLowerCase() === "f") { event.preventDefault(); focus = cell; make({ kind: MOVES.mark, cell }); }
+    else if (event.key === "Enter") { event.preventDefault(); focus = cell; make({ kind: MOVES.reveal, cell }); }
+  });
+  const timer = setInterval(() => { if (started !== null && !disposed) renderStats(); }, 1000);
+  const handle: JiraiMount = {
+    game: () => structuredClone(current), progress: () => gameProgress(current), play: (cell, mark = false) => make({ kind: mark ? MOVES.mark : MOVES.reveal, cell }), hint: showHint,
+    restart: () => { if (disposed) return; stopWorker(); elapsed = 0; started = null; report(newGame(current.settings)); },
+    load: (settings: Settings, progress?: string) => {
+      if (disposed) return;
+      const restored = progress === undefined ? newGame(settings) : gameFromProgress(progress);
+      if (restored === null) throw new Error("Invalid saved Minesweeper game.");
+      stopWorker(); elapsed = 0; started = null; focus = activeCells(restored.settings)[0]!; report(restored);
+    },
+    set: (changes) => { draw = { ...draw, ...changes }; render(); },
+    destroy: () => { disposed = true; stopWorker(); cancelHold(); clearInterval(timer); if (dialog.open) dialog.close(); root.remove(); dialog.remove(); },
+  };
+  if (current.status === STATUSES.playing) started = Date.now();
+  render(); return handle;
+}

package/src/play-entry.ts

@@ -0,0 +1,3 @@
+export { mountJirai } from "./mount.ts";
+export type { JiraiMount, MountOptions } from "./ui.types.ts";
+export { STRINGS } from "./strings.ts";

package/src/random.ts

@@ -0,0 +1,20 @@
+/** Mulberry32, pinned by the replay tests: changing it would change every kept board. */
+export function seededRandom(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+/** Fisher–Yates on a copy. A shuffle never changes the list given. */
+export function shuffled<T>(items: readonly T[], random: () => number): T[] {
+  const out = [...items];
+  for (let i = out.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(random() * (i + 1));
+    [out[i], out[j]] = [out[j]!, out[i]!];
+  }
+  return out;
+}

package/src/react.tsx

@@ -0,0 +1,17 @@
+import { useEffect, useRef } from "react";
+import { mountJirai } from "./mount.ts";
+import type { JiraiProps } from "./react.types.ts";
+
+/** The plain-DOM game as a React component. Options are read on mount; give it a new key to load a new board. */
+export function JiraiBoard({ settings, progress, material, pieces, language, controls, onChange, onFinish, onError, ...element }: JiraiProps) {
+  const host = useRef<HTMLDivElement>(null);
+  const latest = useRef({ onChange, onFinish, onError });
+  useEffect(() => { latest.current = { onChange, onFinish, onError }; });
+  useEffect(() => {
+    if (host.current === null) return;
+    const board = mountJirai(host.current, { settings, progress, material, pieces, language, controls,
+      onChange: (game) => latest.current.onChange?.(game), onFinish: (game) => latest.current.onFinish?.(game), onError: (error) => latest.current.onError?.(error) });
+    return () => board.destroy();
+  }, []);
+  return <div ref={host} {...element} />;
+}

package/src/react.types.ts

@@ -0,0 +1,3 @@
+import type { HTMLAttributes } from "react";
+import type { MountOptions } from "./ui.types.ts";
+export type JiraiProps = MountOptions & Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "onError">;