@johnmorrisdotca/jirai 0.1.0 → 0.2.1

package/dist/orthogonal.d.ts

@@ -0,0 +1,17 @@
+import type { Board, GenerationOptions, Game, Settings } from "./jirai.types.ts";
+/** Identifies the four-neighbour rules and progress-code format. */
+export declare const ORTHOGONAL_VARIANT: "orthogonal";
+/** Settings accepted by the four-neighbour-specific helpers. */
+export type OrthogonalSettings = Omit<Settings, "grid">;
+/** Starts a game under four-neighbour rules. */
+export declare function newOrthogonalGame(settings: OrthogonalSettings): Game;
+/** Deals a board whose clues count only up, down, left and right. */
+export declare function makeOrthogonalBoard(settings: OrthogonalSettings, first: number, options?: GenerationOptions): Board;
+/** Returns the adjacent cells under the orthogonal rules. */
+export declare function orthogonalNeighbours(settings: OrthogonalSettings, cell: number): number[];
+/** Gives a clue-only deduction; flags remain notes and cannot influence the result. */
+export declare function orthogonalHint(game: Game): import("./jirai.types.ts").Deduction;
+/** Encodes an orthogonal game with an explicit variant marker and version 2. */
+export declare function encodeOrthogonalGame(game: Game): string;
+/** Restores only version 2 orthogonal progress records. */
+export declare function decodeOrthogonalGame(code: string): Game | null;

package/dist/orthogonal.js

@@ -0,0 +1,39 @@
+import { deduce } from "./deduce.js";
+import { newGame, visibleGame } from "./game.js";
+import { makeBoard } from "./generate.js";
+import { neighbours, validSettings } from "./grid.js";
+import { gameFromProgress, gameProgress } from "./keep.js";
+/** Identifies the four-neighbour rules and progress-code format. */
+export const ORTHOGONAL_VARIANT = "orthogonal";
+/** Starts a game under four-neighbour rules. */
+export function newOrthogonalGame(settings) {
+    return newGame({ ...settings, grid: ORTHOGONAL_VARIANT });
+}
+/** Deals a board whose clues count only up, down, left and right. */
+export function makeOrthogonalBoard(settings, first, options) {
+    return makeBoard({ ...settings, grid: ORTHOGONAL_VARIANT }, first, options);
+}
+/** Returns the adjacent cells under the orthogonal rules. */
+export function orthogonalNeighbours(settings, cell) {
+    const complete = { ...settings, grid: ORTHOGONAL_VARIANT };
+    if (!validSettings(complete))
+        throw new RangeError("Invalid orthogonal settings.");
+    return neighbours(complete, cell);
+}
+/** Gives a clue-only deduction; flags remain notes and cannot influence the result. */
+export function orthogonalHint(game) {
+    if (game.settings.grid !== ORTHOGONAL_VARIANT)
+        throw new RangeError("Expected an orthogonal game.");
+    return deduce(visibleGame(game));
+}
+/** Encodes an orthogonal game with an explicit variant marker and version 2. */
+export function encodeOrthogonalGame(game) {
+    if (game.settings.grid !== ORTHOGONAL_VARIANT)
+        throw new RangeError("Expected an orthogonal game.");
+    return gameProgress(game);
+}
+/** Restores only version 2 orthogonal progress records. */
+export function decodeOrthogonalGame(code) {
+    const game = gameFromProgress(code);
+    return game?.settings.grid === ORTHOGONAL_VARIANT ? game : null;
+}

package/dist/react.d.ts

@@ -1,3 +1,3 @@
 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. */
+/** Renders the DOM player inside a React-owned host. Options are read on mount; use a new key to load a new board. */
 export declare function JiraiBoard({ settings, progress, material, pieces, language, controls, onChange, onFinish, onError, ...element }: JiraiProps): import("react").JSX.Element;

package/dist/react.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useRef } from "react";
 import { mountJirai } from "./mount.js";
-/** The plain-DOM game as a React component. Options are read on mount; give it a new key to load a new board. */
+/** Renders the DOM player inside a React-owned host. Options are read on mount; use a new key to load a new board. */
 export function JiraiBoard({ settings, progress, material, pieces, language, controls, onChange, onFinish, onError, ...element }) {
     const host = useRef(null);
     const latest = useRef({ onChange, onFinish, onError });

package/dist/react.types.d.ts

@@ -1,3 +1,4 @@
 import type { HTMLAttributes } from "react";
 import type { MountOptions } from "./ui.types.ts";
+/** Mount options plus standard div attributes for the React wrapper. */
 export type JiraiProps = MountOptions & Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "onError">;

package/dist/shape.d.ts

@@ -1,5 +1,7 @@
 import type { Settings } from "./jirai.types.ts";
+/** Board silhouettes supported by settings. */
 export declare const SHAPES: readonly ["rectangle", "heart", "star", "hexagon"];
 /** Row-major addresses stay stable; omitted cells have no clue and no neighbours. */
 export declare function activeCell(settings: Settings, cell: number): boolean;
+/** Returns all active cells in stable row-major order. */
 export declare function activeCells(settings: Settings): number[];

package/dist/shape.js

@@ -1,3 +1,4 @@
+/** Board silhouettes supported by settings. */
 export const SHAPES = ["rectangle", "heart", "star", "hexagon"];
 /** Row-major addresses stay stable; omitted cells have no clue and no neighbours. */
 export function activeCell(settings, cell) {
@@ -28,6 +29,7 @@ export function activeCell(settings, cell) {
         default: return true;
     }
 }
+/** Returns all active cells in stable row-major order. */
 export function activeCells(settings) {
     return Array.from({ length: settings.width * settings.height }, (_, cell) => cell).filter(cell => activeCell(settings, cell));
 }

package/dist/strings.d.ts

@@ -1,4 +1,5 @@
 import type { Language } from "./jirai.types.ts";
+/** Built-in English and Japanese strings used by the player and renderer. */
 export declare const STRINGS: {
     readonly en: {
         readonly board: "Minesweeper board";
@@ -67,4 +68,5 @@ export declare const STRINGS: {
         readonly error: "推測なしで解ける盤が見つかりませんでした。別のシード、別の開始マス、または少ない地雷で試してください。";
     };
 };
+/** Returns the built-in interface strings for a locale. */
 export declare function words(language?: Language): typeof STRINGS["en"] | typeof STRINGS["ja"];

package/dist/strings.js

@@ -1,3 +1,4 @@
+/** Built-in English and Japanese strings used by the player and renderer. */
 export const STRINGS = {
     en: {
         board: "Minesweeper board", covered: "covered", flag: "flagged", question: "uncertain", empty: "empty", mine: "mine", wrong: "incorrect flag",
@@ -14,4 +15,5 @@ export const STRINGS = {
         error: "推測なしで解ける盤が見つかりませんでした。別のシード、別の開始マス、または少ない地雷で試してください。",
     },
 };
+/** Returns the built-in interface strings for a locale. */
 export function words(language = "en") { return STRINGS[language]; }

package/dist/ui.types.d.ts

@@ -1,10 +1,12 @@
 import type { Game, Language, Material, Pieces, Settings } from "./jirai.types.ts";
+/** Appearance and optional hint marker used by drawing and play. */
 export type DrawOptions = {
     material?: Material;
     pieces?: Pieces;
     language?: Language;
     hint?: number | null;
 };
+/** Accessible presentation data for one active board cell. */
 export type CellModel = {
     cell: number;
     x: number;
@@ -16,11 +18,13 @@ export type CellModel = {
     kind: string;
     hint: boolean;
 };
+/** Layout and cell presentation returned by `boardModel`. */
 export type BoardModel = {
     width: number;
     height: number;
     cells: CellModel[];
 };
+/** Initial game, appearance, control, and lifecycle callbacks for a mounted board. */
 export type MountOptions = DrawOptions & {
     settings?: Settings;
     progress?: string;
@@ -29,6 +33,7 @@ export type MountOptions = DrawOptions & {
     onFinish?: (game: Game) => void;
     onError?: (error: Error) => void;
 };
+/** Controls for reading and operating a mounted board. */
 export type JiraiMount = {
     game: () => Game;
     progress: () => string;

package/package.json

@@ -1,45 +1,132 @@
 {
   "name": "@johnmorrisdotca/jirai",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Minesweeper on square, hexagonal and wraparound boards: 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",
   "author": "John Morris",
-  "repository": { "type": "git", "url": "git+https://github.com/johnmorrisdotca/jirai.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnmorrisdotca/jirai.git"
+  },
   "homepage": "https://johnmorrisdotca.github.io/jirai/",
-  "bugs": { "url": "https://github.com/johnmorrisdotca/jirai/issues" },
-  "keywords": ["minesweeper", "puzzle", "hexagonal", "no-guess", "typescript", "seeded", "web-component", "itsutsu"],
+  "bugs": {
+    "url": "https://github.com/johnmorrisdotca/jirai/issues"
+  },
+  "keywords": [
+    "minesweeper",
+    "mines",
+    "minefield",
+    "logic-puzzle",
+    "deduction-puzzle",
+    "number-clues",
+    "hexagonal-minesweeper",
+    "hex-grid",
+    "orthogonal-minesweeper",
+    "four-neighbour",
+    "four-neighbor",
+    "eight-neighbour",
+    "eight-neighbor",
+    "wraparound-grid",
+    "no-guess",
+    "no-guess-minesweeper",
+    "seeded-puzzle",
+    "daily-puzzle",
+    "puzzle-generator",
+    "puzzle-solver",
+    "typescript",
+    "javascript",
+    "svg",
+    "accessible",
+    "keyboard",
+    "touch",
+    "web-component",
+    "custom-element",
+    "react-component",
+    "zero-dependencies",
+    "board-game",
+    "logic-game",
+    "grid-game"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
-    "./play": { "types": "./dist/play-entry.d.ts", "default": "./dist/play-entry.js" },
-    "./draw": { "types": "./dist/draw-entry.d.ts", "default": "./dist/draw-entry.js" },
-    "./element": { "types": "./dist/element.d.ts", "default": "./dist/element.js" },
-    "./element/define": { "types": "./dist/element-define.d.ts", "default": "./dist/element-define.js" },
-    "./react": { "types": "./dist/react.d.ts", "default": "./dist/react.js" }
-  },
-  "sideEffects": ["./dist/element-define.js"],
-  "files": ["dist", "src", "README.md", "LICENSE", "CHANGELOG.md"],
-  "engines": { "node": ">=22" },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./orthogonal": {
+      "types": "./dist/orthogonal.d.ts",
+      "default": "./dist/orthogonal.js"
+    },
+    "./play": {
+      "types": "./dist/play-entry.d.ts",
+      "default": "./dist/play-entry.js"
+    },
+    "./draw": {
+      "types": "./dist/draw-entry.d.ts",
+      "default": "./dist/draw-entry.js"
+    },
+    "./element": {
+      "types": "./dist/element.d.ts",
+      "default": "./dist/element.js"
+    },
+    "./element/define": {
+      "types": "./dist/element-define.d.ts",
+      "default": "./dist/element-define.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    }
+  },
+  "sideEffects": [
+    "./dist/element-define.js"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.check.json",
     "lint": "eslint .",
     "test": "vitest run",
-    "check": "pnpm lint && pnpm typecheck && pnpm test",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm check:presentation",
     "site": "pnpm build && node scripts/site.mjs",
     "test:demo": "pnpm site && playwright test",
     "test:package": "pnpm build && node scripts/check-package.mjs",
-    "prepublishOnly": "pnpm check && pnpm test:package"
+    "prepublishOnly": "pnpm check && pnpm test:package",
+    "check:presentation": "node scripts/check-presentation.mjs",
+    "pictures": "pnpm site && node scripts/readme-pictures.mjs"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   },
-  "peerDependencies": { "react": ">=18" },
-  "peerDependenciesMeta": { "react": { "optional": true } },
   "devDependencies": {
-    "@eslint/js": "^9.0.0", "eslint": "^9.0.0", "typescript-eslint": "^8.0.0",
-    "typescript": "^5.9.0", "vitest": "^4.0.0", "@playwright/test": "^1.58.0",
-    "@types/react": "^19.0.0", "react": "^19.0.0"
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "typescript-eslint": "^8.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0",
+    "@playwright/test": "^1.58.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
   },
-  "publishConfig": { "access": "public" },
   "packageManager": "pnpm@10.11.0"
 }

package/src/element.ts

@@ -5,6 +5,7 @@ import type { JiraiMount } from "./ui.types.ts";
 
 // Importing this file on a server is harmless; only defineJirai registers the tag.
 const ElementBase = typeof HTMLElement === "undefined" ? class {} as typeof HTMLElement : HTMLElement;
+/** Configurable `<jirai-board>` element that owns its mounted game. */
 export class JiraiElement extends ElementBase {
   private mounted: JiraiMount | null = null;
   static observedAttributes = ["width", "height", "mines", "seed", "grid", "shape", "no-guess", "material", "pieces", "lang"];
@@ -21,4 +22,5 @@ export class JiraiElement extends ElementBase {
     } catch (error) { this.dispatchEvent(new CustomEvent("jirai-error", { detail: error })); }
   }
 }
+/** Registers the `<jirai-board>` custom element once in a registry. */
 export function defineJirai(registry: CustomElementRegistry = customElements): void { if (!registry.get("jirai-board")) registry.define("jirai-board", JiraiElement); }

package/src/family.test.js

@@ -0,0 +1,105 @@
+// family.test.js: what every package of the family holds the same way, held by one test copied unchanged into
+// each repository (src/family.test.js, or test/family.test.js in Kyuubu). It reads files and runs nothing else.
+// Changing a shared file means changing it in every repository, with the new hash recorded here.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { familyBlockOf, familyReadmeBlock } from "../scripts/family-readme.mjs";
+import { FAMILY, FAMILY_PITCH, FAMILY_TEMPLATE_VERSION } from "../scripts/family-template.mjs";
+import { releaseNotes } from "../scripts/release-notes.mjs";
+
+const read = (path) => readFileSync(path, "utf8").replace(/\r\n/g, "\n");
+const sha = (path) => createHash("sha256").update(readFileSync(path)).digest("hex");
+const pkg = JSON.parse(read("package.json"));
+const id = pkg.name.replace(/^@[^/]+\//, "");
+
+// The recorded hashes. The template's is the one that says every demo's header and footer, and every README's
+// list of the family, are the same text.
+const TEMPLATE = { version: "2026-10-05", sha256: "061b5ed89c345dccb6e029d5091dff0a5bbc4a9b57812fbcd0bd619038bdb7f1" };
+const FILES = {
+  "scripts/family-readme.mjs": "3c9d5b2cbf17a92d31bced98edac7f544616edb0dff90bf2d141722a9d4516c5",
+  "scripts/release-notes.mjs": "efab0fb78ad05973a8885624c0d2ce3b458b55799c11eabaa5176603ce8cd1e9",
+  "scripts/community/SECURITY.md": "ff6f650be7789396233671d2558439736efe7f96a1d1d39115dd5cf94d29275c",
+  "scripts/community/CODE_OF_CONDUCT.md": "34da1f56f004ce8f7f95d4449b64d2ecb5827dd9f0d4eea1da351a20713ebe70",
+};
+
+describe("the family template", () => {
+  it("is the one file, byte for byte, in every package", () => {
+    expect(FAMILY_TEMPLATE_VERSION).toBe(TEMPLATE.version);
+    expect(sha("scripts/family-template.mjs")).toBe(TEMPLATE.sha256);
+  });
+
+  it("lists every package of the family, in order, each with its Japanese name and a line on it", () => {
+    expect(FAMILY.map((one) => one.id)).toEqual([
+      "korokoro", "kyuubu", "hitotsu", "toranpu", "tane", "narabe", "tenka", "kumimoji", "tsunagi", "jarajara",
+      "suido", "domino", "kotoba", "sugoroku", "kazu", "meikyuu", "hikidashi", "chizu", "bushu", "tobiishi", "jirai", "gunjin",
+    ]);
+    for (const one of FAMILY) {
+      expect(one.name, one.id).toBe(one.id[0].toUpperCase() + one.id.slice(1));
+      expect(one.kana, one.id).toMatch(/\S/);
+      expect(FAMILY_PITCH[one.id], one.id).toMatch(/^[^A-Z.].*[^.]$/);
+    }
+    expect(Object.keys(FAMILY_PITCH).sort()).toEqual(FAMILY.map((one) => one.id).sort());
+    expect(FAMILY.map((one) => one.id)).toContain(id);
+  });
+
+  it("is what this package's footer reads: the demo site names the family through it", () => {
+    expect(read("scripts/site.mjs")).toContain("familyFooter(");
+  });
+});
+
+describe("the files every package shares", () => {
+  it("are copied unchanged: the README writer, the release notes, and the family's SECURITY.md and CODE_OF_CONDUCT.md", () => {
+    for (const [path, hash] of Object.entries(FILES)) expect(sha(path), path).toBe(hash);
+  });
+
+  it("SECURITY.md and CODE_OF_CONDUCT.md are the master text of github.com/johnmorrisdotca/.github, which scripts/community keeps a copy of", () => {
+    for (const file of ["SECURITY.md", "CODE_OF_CONDUCT.md"]) expect(read(file), file).toBe(read(`scripts/community/${file}`));
+  });
+});
+
+describe("the README's family", () => {
+  const readme = read("README.md");
+
+  it("is the block scripts/family-readme.mjs writes from the template, under a heading of its own", () => {
+    const block = familyBlockOf(readme);
+    expect(block, "README.md has no family markers").not.toBeNull();
+    expect(block).toBe(familyReadmeBlock(id));
+    expect(readme.split("<!-- family:start").length - 1).toBe(1);
+    expect(readme).toMatch(/\n#{2,3} The family\n+<!-- family:start/);
+  });
+
+  it("names every package once, as a link", () => {
+    const block = familyBlockOf(readme);
+    for (const one of FAMILY) expect(block.split(`](https://github.com/johnmorrisdotca/${one.id})`).length - 1, one.id).toBe(1);
+  });
+});
+
+describe("the release notes", () => {
+  it("are the changelog's section for the version, which the Release workflow puts on the GitHub release", () => {
+    const log = "# Changelog\n\n## [Unreleased]\n\n## [1.2.0] - 2026-01-02\n\n### Added\n\n- A thing.\n\n## [1.1.0] - 2026-01-01\n\n- Older.\n\n[Unreleased]: https://example.test\n";
+    expect(releaseNotes(log, "1.2.0")).toBe("### Added\n\n- A thing.");
+    expect(releaseNotes(log, "1.1.0")).toBe("- Older.");
+    expect(releaseNotes(log, "9.9.9")).toBeNull();
+    expect(releaseNotes(read("CHANGELOG.md"), pkg.version)?.length, `CHANGELOG.md has nothing under ## [${pkg.version}]`).toBeGreaterThan(40);
+    const workflow = read(".github/workflows/release.yml");
+    expect(workflow).toContain("scripts/release-notes.mjs");
+    expect(workflow).not.toContain("See CHANGELOG.md.");
+  });
+
+  it("come from a changelog in Keep a Changelog form: an Unreleased heading, then each version in brackets with its date", () => {
+    const log = read("CHANGELOG.md");
+    expect(log).toContain("\n## [Unreleased]\n");
+    expect(log).toMatch(/^## \[\d+\.\d+\.\d+\] - \d{4}-\d{2}-\d{2}$/m);
+    expect(log).not.toMatch(/^## \d/m);
+  });
+});
+
+describe("Node", () => {
+  it("is 22 or later: engines, the CI matrix, and the words in the README and CONTRIBUTING", () => {
+    expect(pkg.engines.node).toBe(">=22");
+    expect(read(".github/workflows/ci.yml")).toMatch(/node: \[22, 24\]/);
+    expect(read(".github/workflows/ci.yml")).not.toMatch(/node: \[[^\]]*\b(18|20)\b/);
+    for (const file of ["README.md", "CONTRIBUTING.md"]) expect(read(file), file).not.toMatch(/\bNode(\.js)? (v)?(18|20)\b|>= ?20\b/);
+  });
+});

package/src/game.ts

@@ -5,6 +5,7 @@ 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";
 
+/** Creates an unstarted game with covered cells and no dealt answer. */
 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 };
@@ -16,7 +17,7 @@ export function visibleGame(game: Game): VisibleGame {
     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. */
+/** Attaches a worker-dealt board that matches the game's settings, preserving existing moves. */
 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 };

package/src/grid.ts

@@ -17,6 +17,7 @@ export function validSettings(value: unknown): value is Settings {
     && (s.opening === "safe" || s.opening === "clear")
     && Number.isInteger(s.seed) && s.seed >= 0 && s.seed <= 0xffffffff;
 }
+/** Reports whether a row-major cell is inside the board's active shape. */
 export function validCell(settings: Settings, cell: number): boolean {
   return Number.isInteger(cell) && cell >= 0 && cell < settings.width * settings.height && activeCell(settings, cell);
 }
@@ -37,6 +38,7 @@ export function neighbours(settings: Settings, cell: number): number[] {
   }
   return [...out].sort((a, b) => a - b);
 }
+/** Precomputes the neighbour list for each row-major cell. */
 export function neighboursOf(settings: Settings): number[][] {
   return Array.from({ length: settings.width * settings.height }, (_, cell) => neighbours(settings, cell));
 }

package/src/index.ts

@@ -7,6 +7,9 @@ export * from "./game.ts";
 export * from "./deduce.ts";
 export * from "./keep.ts";
 export { seededRandom } from "./random.ts";
-export const VERSION = "0.1.0";
+/** Package version, kept in step with the release metadata. */
+export const VERSION = "0.2.1";
 
 export { SHAPES, activeCell, activeCells } from "./shape.ts";
+
+export * from "./orthogonal.ts";

package/src/jirai.constants.ts

@@ -1,15 +1,21 @@
 import type { Grid, Settings } from "./jirai.types.ts";
 
-export const GRIDS = { square: "square", hex: "hex", wrap: "wrap" } as const;
+/** Names for the supported square, four-neighbour, hex, and wrap grids. */
+export const GRIDS = { square: "square", orthogonal: "orthogonal", hex: "hex", wrap: "wrap" } as const;
+/** Names for the game lifecycle states. */
 export const STATUSES = { ready: "ready", playing: "playing", won: "won", lost: "lost" } as const;
+/** Names for the cell mark cycle. */
 export const MARKS = { covered: "covered", flag: "flag", question: "question", open: "open" } as const;
+/** Names for the moves accepted by the engine. */
 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. */
+/** Neighbour offsets and edge behaviour for each topology. Hex coordinates are axial: each 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 },
 };
+/** Common minefield dimensions and mine counts. */
 export const PRESETS = {
   beginner: { width: 9, height: 9, mines: 10 },
   intermediate: { width: 16, height: 16, mines: 40 },
@@ -17,9 +23,15 @@ export const PRESETS = {
   wide: { width: 21, height: 9, mines: 24 },
   tall: { width: 9, height: 21, mines: 24 },
 } as const;
+/** Default beginner game, with a verified no-guess board and clear opening. */
 export const DEFAULT_SETTINGS: Settings = { ...PRESETS.beginner, 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. */
 export const GENERATION_ATTEMPTS = 128;
+/** Largest frontier enumerated for exact deductions. */
 export const ENUMERATION_CELLS = 18;
+/** Maximum partial assignments checked in one exact deduction search. */
 export const ENUMERATION_NODES = 100_000;

package/src/jirai.types.ts

@@ -1,7 +1,10 @@
-/** A cell's number is its row-major place on the board, starting at zero. */
-export type Grid = "square" | "hex" | "wrap";
+/** Neighbour topology used to count the clues around each cell. */
+export type Grid = "square" | "orthogonal" | "hex" | "wrap";
+/** 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. */
 export type Mark = "covered" | "flag" | "question" | "open";
+/** Board dimensions and rules used to deal and validate a game. */
 export type Settings = {
   /** Shape omits cells; rectangle is the compatible default. Wrap requires rectangle. */
   shape?: "rectangle" | "heart" | "star" | "hexagon";
@@ -15,7 +18,9 @@ export type Settings = {
   opening: "safe" | "clear";
   seed: number;
 };
+/** A reveal, mark-cycle, or numbered-cell chord applied to a game. */
 export type Move = { kind: "reveal" | "mark" | "chord"; cell: number };
+/** A dealt board including its answer; keep it off public clients. */
 export type Board = {
   settings: Settings;
   mines: readonly boolean[];
@@ -34,6 +39,7 @@ export type Game = {
   /** A proved hint has been shown during this run. */
   helped: boolean;
 };
+/** Answer-free state suitable for deductions, hints, and public display. */
 export type VisibleGame = {
   settings: Settings;
   /** Null is hidden, including flags. Only opened cells give a clue. */
@@ -41,7 +47,9 @@ export type VisibleGame = {
   marks: readonly Mark[];
   status: Status;
 };
+/** An exact count over unknown cells, with the clues that supplied it. */
 export type Constraint = { cells: readonly number[]; mines: number; sources: readonly number[] };
+/** Certain safe cells and mines proved from visible clues. */
 export type Deduction = {
   safe: readonly number[];
   mines: readonly number[];
@@ -50,7 +58,11 @@ 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. */
 export type GenerationOptions = { attempts?: number; enumerate?: boolean };
+/** Supported interface copy locales. */
 export type Language = "en" | "ja";
+/** Board colours for drawing and mounted play. */
 export type Material = "ivory" | "wood" | "slate";
+/** Symbols used to mark mines. */
 export type Pieces = "flags" | "stones" | "flowers";

package/src/keep.ts

@@ -4,6 +4,9 @@ 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 });
 }
 
@@ -12,7 +15,10 @@ 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;
+    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) {
@@ -29,6 +35,7 @@ export function gameFromProgress(progress: string): Game | null {
 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;
+  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;
 }