@johnmorrisdotca/jirai 0.0.0-stage → 0.2.0

package/src/flood.ts

@@ -0,0 +1,12 @@
+/** Reveal connected empty ground and its numbered boundary, without recursion. */
+export function flood(clues: readonly number[], adjacent: readonly (readonly number[])[], open: boolean[], starts: readonly number[], blocked: ReadonlySet<number> = new Set()): void {
+  const queue = [...starts];
+  const queued = new Set(queue);
+  for (let at = 0; at < queue.length; at += 1) {
+    const cell = queue[at]!;
+    if (open[cell] || blocked.has(cell) || clues[cell] === undefined || clues[cell]! < 0) continue;
+    open[cell] = true;
+    if (clues[cell] !== 0) continue;
+    for (const n of adjacent[cell]!) if (!open[n] && !queued.has(n)) { queue.push(n); queued.add(n); }
+  }
+}

package/src/game.test.ts

@@ -0,0 +1,172 @@
+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, validCell, validSettings } from "./grid.ts";
+import { gameFromProgress, gameProgress, dailySeed } from "./keep.ts";
+import { boardModel } from "./draw.ts";
+import { hintFor } from "./deduce.ts";
+import type { Board, Game, Settings } from "./jirai.types.ts";
+import { decodeOrthogonalGame, encodeOrthogonalGame, makeOrthogonalBoard, newOrthogonalGame, orthogonalHint, orthogonalNeighbours } from "./orthogonal.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 grid topologies", () => {
+  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 four orthogonal neighbours, six hex neighbours, eight square neighbours, and joins both wrap seams", () => {
+    expect(neighbours({ ...DEFAULT_SETTINGS, grid: GRIDS.orthogonal }, 40)).toHaveLength(4);
+    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("uses only orthogonal clues, preserves playable voids, and verifies a no-guess deal", () => {
+    const settings = { ...DEFAULT_SETTINGS, width: 9, height: 9, mines: 10, grid: GRIDS.orthogonal, seed: 19 };
+    const board = makeBoard(settings, 40);
+    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(next => board.mines[next]).length);
+    }
+    expect(isSolvable(board)).toBe(true);
+    const shaped = { ...settings, shape: "heart" as const };
+    const shapedBoard = makeBoard(shaped, 40);
+    for (let cell = 0; cell < 81; cell += 1) if (!validCell(shaped, cell)) {
+      expect(shapedBoard.mines[cell]).toBe(false);
+      expect(shapedBoard.clues[cell]).toBe(-2);
+      expect(neighbours(shaped, cell)).toEqual([]);
+    }
+    const playing = play(newGame(settings), { kind: MOVES.reveal, cell: 40 });
+    const proof = hintFor(visibleGame(playing));
+    expect(proof.safe.every(cell => !playing.board!.mines[cell])).toBe(true);
+    expect(proof.mines.every(cell => playing.board!.mines[cell])).toBe(true);
+  });
+  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("keeps orthogonal save records distinct and preserves legacy square codes", () => {
+    const legacy = JSON.stringify({ version: 1, settings: DEFAULT_SETTINGS, moves: [], helped: false });
+    expect(gameFromProgress(legacy)).toEqual(newGame());
+    const orthogonal = newGame({ ...DEFAULT_SETTINGS, grid: GRIDS.orthogonal });
+    const code = gameProgress(orthogonal);
+    expect(JSON.parse(code)).toMatchObject({ version: 2, variant: "orthogonal", settings: { grid: "orthogonal" } });
+    expect(gameFromProgress(code)).toEqual(orthogonal);
+    expect(gameFromProgress(JSON.stringify({ ...JSON.parse(code), variant: "square" }))).toBeNull();
+  });
+  it("exposes focused orthogonal helpers and variant-only progress codes", () => {
+    const settings = { ...DEFAULT_SETTINGS, width: 9, height: 9, mines: 10, seed: 4 };
+    const game = newOrthogonalGame(settings);
+    expect(game.settings.grid).toBe("orthogonal");
+    expect(orthogonalNeighbours(settings, 40)).toHaveLength(4);
+    expect(makeOrthogonalBoard(settings, 40).settings.grid).toBe("orthogonal");
+    expect(orthogonalHint(play(game, { kind: MOVES.reveal, cell: 40 })).contradiction).toBe(false);
+    expect(decodeOrthogonalGame(encodeOrthogonalGame(game))).toEqual(game);
+    expect(decodeOrthogonalGame(gameProgress(newGame()))).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", "orthogonal")).not.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,14 @@
+/** 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.2.0";
+
+export { SHAPES, activeCell, activeCells } from "./shape.ts";
+
+export * from "./orthogonal.ts";

package/src/jirai.constants.ts

@@ -0,0 +1,26 @@
+import type { Grid, Settings } from "./jirai.types.ts";
+
+export const GRIDS = { square: "square", orthogonal: "orthogonal", 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 },
+  orthogonal: { offsets: [[0,-1],[-1,0],[1,0],[0,1]], wrap: false },
+  hex: { offsets: [[-1,0],[1,0],[0,-1],[1,-1],[-1,1],[0,1]], wrap: false },
+  wrap: { offsets: [[-1,-1],[0,-1],[1,-1],[-1,0],[1,0],[-1,1],[0,1],[1,1]], wrap: true },
+};
+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" | "orthogonal" | "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,41 @@
+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 {
+  if (game.settings.grid === "orthogonal") {
+    return JSON.stringify({ version: 2, variant: "orthogonal", settings: game.settings, moves: game.moves, helped: game.helped });
+  }
+  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);
+    const orthogonalCode = data.version === 2 && data.variant === "orthogonal";
+    if ((!orthogonalCode && data.version !== 1) || !validSettings(data.settings)
+      || orthogonalCode !== (data.settings.grid === "orthogonal")
+      || !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;
+  const version = grid === "orthogonal" ? 2 : 1;
+  for (const letter of `jirai:${version}:${day}:${grid}`) hash = Math.imul(hash ^ letter.charCodeAt(0), 16777619) >>> 0;
+  return hash;
+}