@johnmorrisdotca/jirai 0.0.0-stage → 0.1.0

package/dist/shape.js

@@ -0,0 +1,33 @@
+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) {
+    if (!Number.isInteger(cell) || cell < 0 || cell >= settings.width * settings.height)
+        return false;
+    const col = cell % settings.width, row = Math.floor(cell / settings.width);
+    const x = 2 * (col + .5) / settings.width - 1, y = 2 * (row + .5) / settings.height - 1;
+    switch (settings.shape ?? "rectangle") {
+        case "heart": {
+            const hx = x * 1.15, hy = -y * 1.25 + .15;
+            return (hx * hx + hy * hy - 1) ** 3 - hx * hx * hy ** 3 <= 0;
+        }
+        case "star": {
+            // A filled five-point polygon, never a decorative overlay on hidden square cells.
+            const vertices = Array.from({ length: 10 }, (_, i) => {
+                const angle = -Math.PI / 2 + i * Math.PI / 5, radius = i % 2 ? .48 : 1;
+                return [Math.cos(angle) * radius, Math.sin(angle) * radius];
+            });
+            let inside = false;
+            for (let i = 0, j = 9; i < 10; j = i++) {
+                const [xi, yi] = vertices[i], [xj, yj] = vertices[j];
+                if ((yi > y) !== (yj > y) && x < (xj - xi) * (y - yi) / (yj - yi) + xi)
+                    inside = !inside;
+            }
+            return inside;
+        }
+        case "hexagon": return settings.grid === "hex" ? Math.abs(x + y) <= 1 : Math.abs(x) <= 1 - .5 * Math.abs(y);
+        default: return true;
+    }
+}
+export function activeCells(settings) {
+    return Array.from({ length: settings.width * settings.height }, (_, cell) => cell).filter(cell => activeCell(settings, cell));
+}

package/dist/strings.d.ts

@@ -0,0 +1,70 @@
+import type { Language } from "./jirai.types.ts";
+export declare const STRINGS: {
+    readonly en: {
+        readonly board: "Minesweeper board";
+        readonly covered: "covered";
+        readonly flag: "flagged";
+        readonly question: "uncertain";
+        readonly empty: "empty";
+        readonly mine: "mine";
+        readonly wrong: "incorrect flag";
+        readonly ready: "Open a cell to begin. Your first cell is safe.";
+        readonly playing: "Read the numbers. Open every safe cell.";
+        readonly won: "Every safe cell is open. Well played.";
+        readonly lost: "A mine. Try the same board again, or start another.";
+        readonly checking: "Finding a board that can be solved without guessing…";
+        readonly restart: "Start over";
+        readonly hint: "Hint";
+        readonly reveal: "Open";
+        readonly mark: "Mark";
+        readonly mines: "Mines left";
+        readonly time: "Time";
+        readonly moves: "Moves";
+        readonly clear: "Cleared";
+        readonly view: "Just the board";
+        readonly close: "Close";
+        readonly hintNone: "No certain move proved. This position may need a guess.";
+        readonly hintSafe: "This cell is safe.";
+        readonly hintMine: "This cell contains a mine.";
+        readonly count: "The neighbouring count settles it.";
+        readonly overlap: "Compare the overlapping clues.";
+        readonly total: "The total mine count settles it.";
+        readonly enumeration: "Every consistent arrangement gives the same answer.";
+        readonly help: "Tap to open; right-click or hold to mark. Use the arrows to move, Enter to open, F or Space to mark. Tap an open number to clear its neighbours when the flags match.";
+        readonly error: "A verified board was not found. Try another seed, an opening elsewhere, or fewer mines.";
+    };
+    readonly ja: {
+        readonly board: "地雷の盤";
+        readonly covered: "未開封";
+        readonly flag: "旗";
+        readonly question: "不明";
+        readonly empty: "空き";
+        readonly mine: "地雷";
+        readonly wrong: "間違った旗";
+        readonly ready: "マスを開けて始めます。最初のマスは安全です。";
+        readonly playing: "数字を手がかりに、安全なマスをすべて開けましょう。";
+        readonly won: "安全なマスがすべて開きました。クリア！";
+        readonly lost: "地雷でした。同じ盤で再挑戦できます。";
+        readonly checking: "推測なしで解ける盤を探しています…";
+        readonly restart: "やり直す";
+        readonly hint: "ヒント";
+        readonly reveal: "開く";
+        readonly mark: "印を付ける";
+        readonly mines: "残りの地雷";
+        readonly time: "時間";
+        readonly moves: "手数";
+        readonly clear: "開いたマス";
+        readonly view: "盤だけ";
+        readonly close: "閉じる";
+        readonly hintNone: "確実な手は見つかりませんでした。推測が必要かもしれません。";
+        readonly hintSafe: "このマスは安全です。";
+        readonly hintMine: "このマスには地雷があります。";
+        readonly count: "周囲の数字から確定できます。";
+        readonly overlap: "重なった手がかりを比べましょう。";
+        readonly total: "地雷の総数から確定できます。";
+        readonly enumeration: "可能な配置すべてで同じ答えになります。";
+        readonly help: "タップで開く、右クリックか長押しで印を付けます。矢印キーで移動、Enterで開く、FかSpaceで印を付けます。旗の数が合う数字をタップすると周囲が開きます。";
+        readonly error: "推測なしで解ける盤が見つかりませんでした。別のシード、別の開始マス、または少ない地雷で試してください。";
+    };
+};
+export declare function words(language?: Language): typeof STRINGS["en"] | typeof STRINGS["ja"];

package/dist/strings.js

@@ -0,0 +1,17 @@
+export const STRINGS = {
+    en: {
+        board: "Minesweeper board", covered: "covered", flag: "flagged", question: "uncertain", empty: "empty", mine: "mine", wrong: "incorrect flag",
+        ready: "Open a cell to begin. Your first cell is safe.", playing: "Read the numbers. Open every safe cell.", won: "Every safe cell is open. Well played.", lost: "A mine. Try the same board again, or start another.",
+        checking: "Finding a board that can be solved without guessing…", restart: "Start over", hint: "Hint", reveal: "Open", mark: "Mark", mines: "Mines left", time: "Time", moves: "Moves", clear: "Cleared", view: "Just the board", close: "Close", hintNone: "No certain move proved. This position may need a guess.", hintSafe: "This cell is safe.", hintMine: "This cell contains a mine.", count: "The neighbouring count settles it.", overlap: "Compare the overlapping clues.", total: "The total mine count settles it.", enumeration: "Every consistent arrangement gives the same answer.",
+        help: "Tap to open; right-click or hold to mark. Use the arrows to move, Enter to open, F or Space to mark. Tap an open number to clear its neighbours when the flags match.",
+        error: "A verified board was not found. Try another seed, an opening elsewhere, or fewer mines.",
+    },
+    ja: {
+        board: "地雷の盤", covered: "未開封", flag: "旗", question: "不明", empty: "空き", mine: "地雷", wrong: "間違った旗",
+        ready: "マスを開けて始めます。最初のマスは安全です。", playing: "数字を手がかりに、安全なマスをすべて開けましょう。", won: "安全なマスがすべて開きました。クリア！", lost: "地雷でした。同じ盤で再挑戦できます。",
+        checking: "推測なしで解ける盤を探しています…", restart: "やり直す", hint: "ヒント", reveal: "開く", mark: "印を付ける", mines: "残りの地雷", time: "時間", moves: "手数", clear: "開いたマス", view: "盤だけ", close: "閉じる", hintNone: "確実な手は見つかりませんでした。推測が必要かもしれません。", hintSafe: "このマスは安全です。", hintMine: "このマスには地雷があります。", count: "周囲の数字から確定できます。", overlap: "重なった手がかりを比べましょう。", total: "地雷の総数から確定できます。", enumeration: "可能な配置すべてで同じ答えになります。",
+        help: "タップで開く、右クリックか長押しで印を付けます。矢印キーで移動、Enterで開く、FかSpaceで印を付けます。旗の数が合う数字をタップすると周囲が開きます。",
+        error: "推測なしで解ける盤が見つかりませんでした。別のシード、別の開始マス、または少ない地雷で試してください。",
+    },
+};
+export function words(language = "en") { return STRINGS[language]; }

package/dist/style.d.ts

@@ -0,0 +1,2 @@
+/** Scoped to one mounted board. Its host supplies the font and may override every colour. */
+export declare const JIRAI_STYLE = "\n.jr-root{--jr-ground:#a98954;--jr-cover:#fbf8f1;--jr-open:#efe8d8;--jr-line:#cfc6b2;--jr-ink:#1f2320;--jr-accent:#2f7a4f;color:var(--jr-ui-ink,var(--jr-ink));font:inherit;position:relative}\n.jr-root[data-material=wood]{--jr-ground:#ae804a;--jr-cover:#e0bb7e;--jr-open:#c69d63;--jr-line:#936e40;--jr-ink:#352c20;background-image:repeating-linear-gradient(4deg,transparent 0 8px,#4b2b0c08 9px 10px)}\n.jr-root[data-material=slate]{--jr-ground:#252e32;--jr-cover:#455359;--jr-open:#303c41;--jr-line:#62747a;--jr-ink:#f3f0e5;--jr-accent:#b7d298}\n.jr-scroll{overflow:auto;padding:12px;border:1px solid var(--jr-line);border-radius:14px;background:var(--jr-ground);overscroll-behavior:contain}\n.jr-board{position:relative;width:100%;min-width:240px;margin:auto;isolation:isolate}\n.jr-cell{position:absolute;box-sizing:border-box;display:flex;align-items:center;justify-content:center;border:1px solid var(--jr-line);border-radius:4px;background:var(--jr-cover);color:var(--jr-ink);font:700 clamp(12px,2vw,22px)/1 ui-monospace,monospace;box-shadow:inset 0 2px 1px #fff7,inset 0 -2px 1px #0001;cursor:pointer;user-select:none;-webkit-user-select:none;touch-action:manipulation;padding:0}\n.jr-root[data-grid=hex] .jr-cell{clip-path:polygon(50% 0,100% 25%,100% 75%,50% 100%,0 75%,0 25%);border-radius:0}\n.jr-cell[data-kind=open]{background:var(--jr-open);box-shadow:none}\n.jr-cell[data-number=\"1\"]{color:#326ca0}.jr-cell[data-number=\"2\"]{color:#3d763c}.jr-cell[data-number=\"3\"]{color:#a34438}.jr-cell[data-number=\"4\"]{color:#704b97}.jr-cell[data-number=\"5\"]{color:#8c542f}.jr-cell[data-number=\"6\"]{color:#1c777b}\n.jr-root[data-material=slate] .jr-cell[data-kind=open]{color:#e8e6bd}\n.jr-cell[data-kind=flag]{color:var(--jr-accent)}.jr-cell[data-kind=question]{color:#8a702d}\n.jr-cell[data-kind=mine],.jr-cell[data-kind=wrong]{background:#ead4c5;color:#873e32}.jr-cell[data-kind=exploded]{background:#a34d3c;color:white}\n.jr-cell[data-hint=true]{background:#d4e5bc!important;color:#243d24!important;box-shadow:inset 0 0 0 3px #577b3f}\n.jr-cell:focus-visible{outline:none;box-shadow:inset 0 0 0 3px #c0802e;z-index:2}.jr-cell:hover{filter:brightness(.97)}\n.jr-stats{display:flex;gap:18px;flex-wrap:wrap;font-variant-numeric:tabular-nums;margin:0 0 14px}.jr-stat{display:flex;gap:7px;align-items:baseline}.jr-stat small{opacity:.7;font-size:12px}.jr-stat strong{font-size:20px;font-weight:500}\n.jr-status{font-size:14px;line-height:1.5;min-height:1.5em;margin:12px 0}.jr-help{font-size:12px;line-height:1.65;opacity:.7}\n.jr-controls{display:flex;flex-wrap:wrap;gap:8px}.jr-button{font:inherit;font-size:13px;border:1px solid var(--jr-line);border-radius:999px;min-height:44px;padding:0 14px;background:var(--jr-ui-surface,var(--jr-cover));color:var(--jr-ui-ink,var(--jr-ink));border-color:var(--jr-ui-line,var(--jr-line));cursor:pointer}.jr-button:disabled{opacity:.5;cursor:wait}.jr-button[aria-pressed=true]{background:var(--jr-accent);color:white}.jr-button:focus-visible{outline:2px solid var(--jr-accent);outline-offset:3px}\n.jr-dialog{border:0;border-radius:20px;padding:24px;max-width:min(96vw,1000px);width:850px;background:var(--surface,#fbf8f1);color:var(--ink,#1f2320);--jr-ui-ink:var(--ink,#1f2320);--jr-ui-surface:var(--surface,#fbf8f1);--jr-ui-line:var(--rule,#ddd6c6);box-sizing:border-box}.jr-dialog::backdrop{background:#172019bb}.jr-dialog .jr-board{max-height:75vh}.jr-close{float:right;margin-bottom:10px}\n@media(prefers-reduced-motion:no-preference){.jr-cell{transition:background .12s}}\n";

package/dist/style.js

@@ -0,0 +1,22 @@
+/** Scoped to one mounted board. Its host supplies the font and may override every colour. */
+export const JIRAI_STYLE = `
+.jr-root{--jr-ground:#a98954;--jr-cover:#fbf8f1;--jr-open:#efe8d8;--jr-line:#cfc6b2;--jr-ink:#1f2320;--jr-accent:#2f7a4f;color:var(--jr-ui-ink,var(--jr-ink));font:inherit;position:relative}
+.jr-root[data-material=wood]{--jr-ground:#ae804a;--jr-cover:#e0bb7e;--jr-open:#c69d63;--jr-line:#936e40;--jr-ink:#352c20;background-image:repeating-linear-gradient(4deg,transparent 0 8px,#4b2b0c08 9px 10px)}
+.jr-root[data-material=slate]{--jr-ground:#252e32;--jr-cover:#455359;--jr-open:#303c41;--jr-line:#62747a;--jr-ink:#f3f0e5;--jr-accent:#b7d298}
+.jr-scroll{overflow:auto;padding:12px;border:1px solid var(--jr-line);border-radius:14px;background:var(--jr-ground);overscroll-behavior:contain}
+.jr-board{position:relative;width:100%;min-width:240px;margin:auto;isolation:isolate}
+.jr-cell{position:absolute;box-sizing:border-box;display:flex;align-items:center;justify-content:center;border:1px solid var(--jr-line);border-radius:4px;background:var(--jr-cover);color:var(--jr-ink);font:700 clamp(12px,2vw,22px)/1 ui-monospace,monospace;box-shadow:inset 0 2px 1px #fff7,inset 0 -2px 1px #0001;cursor:pointer;user-select:none;-webkit-user-select:none;touch-action:manipulation;padding:0}
+.jr-root[data-grid=hex] .jr-cell{clip-path:polygon(50% 0,100% 25%,100% 75%,50% 100%,0 75%,0 25%);border-radius:0}
+.jr-cell[data-kind=open]{background:var(--jr-open);box-shadow:none}
+.jr-cell[data-number="1"]{color:#326ca0}.jr-cell[data-number="2"]{color:#3d763c}.jr-cell[data-number="3"]{color:#a34438}.jr-cell[data-number="4"]{color:#704b97}.jr-cell[data-number="5"]{color:#8c542f}.jr-cell[data-number="6"]{color:#1c777b}
+.jr-root[data-material=slate] .jr-cell[data-kind=open]{color:#e8e6bd}
+.jr-cell[data-kind=flag]{color:var(--jr-accent)}.jr-cell[data-kind=question]{color:#8a702d}
+.jr-cell[data-kind=mine],.jr-cell[data-kind=wrong]{background:#ead4c5;color:#873e32}.jr-cell[data-kind=exploded]{background:#a34d3c;color:white}
+.jr-cell[data-hint=true]{background:#d4e5bc!important;color:#243d24!important;box-shadow:inset 0 0 0 3px #577b3f}
+.jr-cell:focus-visible{outline:none;box-shadow:inset 0 0 0 3px #c0802e;z-index:2}.jr-cell:hover{filter:brightness(.97)}
+.jr-stats{display:flex;gap:18px;flex-wrap:wrap;font-variant-numeric:tabular-nums;margin:0 0 14px}.jr-stat{display:flex;gap:7px;align-items:baseline}.jr-stat small{opacity:.7;font-size:12px}.jr-stat strong{font-size:20px;font-weight:500}
+.jr-status{font-size:14px;line-height:1.5;min-height:1.5em;margin:12px 0}.jr-help{font-size:12px;line-height:1.65;opacity:.7}
+.jr-controls{display:flex;flex-wrap:wrap;gap:8px}.jr-button{font:inherit;font-size:13px;border:1px solid var(--jr-line);border-radius:999px;min-height:44px;padding:0 14px;background:var(--jr-ui-surface,var(--jr-cover));color:var(--jr-ui-ink,var(--jr-ink));border-color:var(--jr-ui-line,var(--jr-line));cursor:pointer}.jr-button:disabled{opacity:.5;cursor:wait}.jr-button[aria-pressed=true]{background:var(--jr-accent);color:white}.jr-button:focus-visible{outline:2px solid var(--jr-accent);outline-offset:3px}
+.jr-dialog{border:0;border-radius:20px;padding:24px;max-width:min(96vw,1000px);width:850px;background:var(--surface,#fbf8f1);color:var(--ink,#1f2320);--jr-ui-ink:var(--ink,#1f2320);--jr-ui-surface:var(--surface,#fbf8f1);--jr-ui-line:var(--rule,#ddd6c6);box-sizing:border-box}.jr-dialog::backdrop{background:#172019bb}.jr-dialog .jr-board{max-height:75vh}.jr-close{float:right;margin-bottom:10px}
+@media(prefers-reduced-motion:no-preference){.jr-cell{transition:background .12s}}
+`;

package/dist/ui.types.d.ts

@@ -0,0 +1,41 @@
+import type { Game, Language, Material, Pieces, Settings } from "./jirai.types.ts";
+export type DrawOptions = {
+    material?: Material;
+    pieces?: Pieces;
+    language?: Language;
+    hint?: number | null;
+};
+export type CellModel = {
+    cell: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    label: string;
+    text: string;
+    kind: string;
+    hint: boolean;
+};
+export type BoardModel = {
+    width: number;
+    height: number;
+    cells: CellModel[];
+};
+export type MountOptions = DrawOptions & {
+    settings?: Settings;
+    progress?: string;
+    controls?: boolean;
+    onChange?: (game: Game) => void;
+    onFinish?: (game: Game) => void;
+    onError?: (error: Error) => void;
+};
+export type JiraiMount = {
+    game: () => Game;
+    progress: () => string;
+    play: (cell: number, mark?: boolean) => void;
+    hint: () => void;
+    restart: () => void;
+    load: (settings: Settings, progress?: string) => void;
+    set: (options: DrawOptions) => void;
+    destroy: () => void;
+};

package/dist/ui.types.js

@@ -0,0 +1 @@
+export {};

package/dist/worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/worker.js

@@ -0,0 +1,10 @@
+import { makeBoard } from "./generate.js";
+// A separate entry: importing the engine or renderer never creates a worker.
+self.addEventListener("message", (event) => {
+    try {
+        self.postMessage({ board: makeBoard(event.data.settings, event.data.first) });
+    }
+    catch (error) {
+        self.postMessage({ error: error instanceof Error ? error.message : String(error) });
+    }
+});

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@johnmorrisdotca/jirai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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" },
+  "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"],
+  "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" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "check": "pnpm lint && pnpm typecheck && pnpm test",
+    "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"
+  },
+  "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"
+  },
+  "publishConfig": { "access": "public" },
+  "packageManager": "pnpm@10.11.0"
+}

package/src/deduce.test.ts

@@ -0,0 +1,47 @@
+import { expect, it } from "vitest";
+import { deduce, hintFor } from "./deduce.ts";
+import { enumerateForced } from "./enumerate.ts";
+import { DEFAULT_SETTINGS, MARKS, STATUSES } from "./jirai.constants.ts";
+import { neighbours } from "./grid.ts";
+import type { VisibleGame, Grid } from "./jirai.types.ts";
+
+it("extracts the 1–2–1 wall pattern without trusting flags", () => {
+  const game: VisibleGame = {
+    settings: { ...DEFAULT_SETTINGS, width: 3, height: 3, mines: 2 }, status: STATUSES.playing,
+    clues: [null,null,null,1,2,1,0,0,0], marks: [MARKS.flag,MARKS.flag,MARKS.covered,...Array(6).fill(MARKS.open)],
+  };
+  const hint = hintFor(game);
+  expect(hint.safe).toContain(1); // A wrongly flagged square is still provably safe.
+});
+
+it("enumeration proves only cells forced in every consistent assignment", () => {
+  const proof = enumerateForced([
+    { cells: [0,1], mines: 1, sources: [3] },
+    { cells: [1,2], mines: 1, sources: [4] },
+    { cells: [0,2], mines: 0, sources: [5] },
+  ]);
+  expect([...proof.safe].sort()).toEqual([0,2]); expect(proof.mines).toEqual([1]);
+  expect(enumerateForced([{ cells: [0,1], mines: 1, sources: [] }]).safe).toEqual([]);
+  expect(enumerateForced([{ cells: [0], mines: 2, sources: [] }]).contradiction).toBe(true);
+});
+
+it("agrees with an independent exhaustive oracle on square, hex and wrapped 3×3 positions", () => {
+  for (const grid of ["square", "hex", "wrap"] as Grid[]) {
+    const settings = { ...DEFAULT_SETTINGS, width: 3, height: 3, mines: 2, grid };
+    for (let firstMine = 0; firstMine < 9; firstMine += 1) for (let secondMine = firstMine + 1; secondMine < 9; secondMine += 1) {
+      const actual = [firstMine, secondMine];
+      const clues = Array.from({ length: 9 }, (_, cell) => !actual.includes(cell) && cell % 2 === 0 ? neighbours(settings, cell).filter((n) => actual.includes(n)).length : null);
+      const possible: number[][] = [];
+      for (let a = 0; a < 9; a += 1) for (let b = a + 1; b < 9; b += 1) {
+        const mines = [a,b];
+        if (mines.some((cell) => clues[cell] !== null)) continue;
+        if (clues.every((clue, cell) => clue === null || neighbours(settings, cell).filter((n) => mines.includes(n)).length === clue)) possible.push(mines);
+      }
+      const game: VisibleGame = { settings, clues, status: STATUSES.playing, marks: clues.map((n) => n === null ? MARKS.flag : MARKS.open) };
+      const result = deduce(game);
+      expect(result.contradiction).toBe(false); expect(possible.length).toBeGreaterThan(0);
+      for (const cell of result.safe) expect(possible.every((mines) => !mines.includes(cell))).toBe(true);
+      for (const cell of result.mines) expect(possible.every((mines) => mines.includes(cell))).toBe(true);
+    }
+  }
+});

package/src/deduce.ts

@@ -0,0 +1,66 @@
+import { enumerateForced } from "./enumerate.ts";
+import { neighboursOf } from "./grid.ts";
+import type { Constraint, Deduction, VisibleGame } from "./jirai.types.ts";
+
+/**
+ * What the clues prove, without reading the answer or trusting a player's
+ * flags. A flag is a note; treating it as evidence makes a bad note a bad hint.
+ */
+export function deduce(game: VisibleGame, knownMines: ReadonlySet<number> = new Set(), enumerate = true): Deduction {
+  const adjacent = neighboursOf(game.settings);
+  const constraints: Constraint[] = [];
+  const empty: Deduction = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
+  for (let cell = 0; cell < game.clues.length; cell += 1) {
+    const clue = game.clues[cell];
+    if (clue === null || clue === undefined || clue < 0) continue;
+    const unknown = adjacent[cell]!.filter((n) => game.clues[n] === null && !knownMines.has(n));
+    const mines = clue - adjacent[cell]!.filter((n) => knownMines.has(n)).length;
+    if (mines < 0 || mines > unknown.length) return { ...empty, contradiction: true };
+    if (unknown.length) constraints.push({ cells: unknown, mines, sources: [cell] });
+  }
+  const unknown = game.clues.flatMap((clue, cell) => clue === null && !knownMines.has(cell) ? [cell] : []);
+  const left = game.settings.mines - knownMines.size;
+  if (left < 0 || left > unknown.length) return { ...empty, contradiction: true };
+  const total: Constraint = { cells: unknown, mines: left, sources: [] };
+  function forced(c: Constraint, reason: Deduction["reason"]): Deduction | null {
+    if (c.mines === 0) return { ...empty, safe: c.cells, reason, sources: c.sources };
+    if (c.mines === c.cells.length) return { ...empty, mines: c.cells, reason, sources: c.sources };
+    return null;
+  }
+  for (const c of constraints) { const result = forced(c, "count"); if (result !== null) return result; }
+  if (unknown.length) { const result = forced(total, "total"); if (result !== null) return result; }
+  // Compare a smaller clue with a larger one, including the mine counter.
+  // Their difference is another exact count. Never subtract mere overlaps.
+  const sets = [...constraints, total].map((c) => new Set(c.cells));
+  const all = [...constraints, total];
+  for (let i = 0; i < all.length; i += 1) for (let j = 0; j < all.length; j += 1) {
+    if (i === j || all[i]!.cells.length >= all[j]!.cells.length) continue;
+    if (!all[i]!.cells.every((cell) => sets[j]!.has(cell))) continue;
+    const c: Constraint = {
+      cells: all[j]!.cells.filter((cell) => !sets[i]!.has(cell)),
+      mines: all[j]!.mines - all[i]!.mines,
+      sources: [...new Set([...all[i]!.sources, ...all[j]!.sources])],
+    };
+    if (c.mines < 0 || c.mines > c.cells.length) return { ...empty, contradiction: true };
+    const result = forced(c, j === all.length - 1 ? "total" : "overlap");
+    if (result !== null) return result;
+  }
+  // A whole-board constraint would join otherwise independent components.
+  // Local enumeration is conservative; the global counter is used above.
+  return enumerate ? enumerateForced(constraints) : empty;
+}
+
+/** Keep discovering certain mines until there is a safe cell or nothing more is proved. */
+export function hintFor(game: VisibleGame): Deduction {
+  const known = new Set<number>();
+  let last: Deduction = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
+  while (known.size <= game.settings.mines) {
+    const result = deduce(game, known);
+    if (result.contradiction || result.safe.length) return result;
+    const fresh = result.mines.filter((cell) => !known.has(cell));
+    if (!fresh.length) return last;
+    last = result;
+    for (const cell of fresh) known.add(cell);
+  }
+  return last;
+}

package/src/draw-entry.ts

@@ -0,0 +1,3 @@
+export { boardModel } from "./draw.ts";
+export type { BoardModel, CellModel, DrawOptions } from "./ui.types.ts";
+export { JIRAI_STYLE } from "./style.ts";

package/src/draw.ts

@@ -0,0 +1,28 @@
+import { activeCell } from "./shape.ts";
+import { GRIDS, MARKS, STATUSES } from "./jirai.constants.ts";
+import { words } from "./strings.ts";
+import type { Game } from "./jirai.types.ts";
+import type { BoardModel, DrawOptions } from "./ui.types.ts";
+
+/** Where the cells sit, and what may be shown. The drawing never exposes a covered clue. */
+export function boardModel(game: Game, options: DrawOptions = {}): BoardModel {
+  const hex = game.settings.grid === GRIDS.hex;
+  const ended = game.status === STATUSES.lost || game.status === STATUSES.won;
+  const say = words(options.language);
+  const width = hex ? game.settings.width + (game.settings.height - 1) / 2 : game.settings.width;
+  const height = hex ? (game.settings.height - 1) * .866 + 1.155 : game.settings.height;
+  const cells = game.marks.flatMap((mark, cell) => {
+    if (!activeCell(game.settings, cell)) return [];
+    const col = cell % game.settings.width, row = Math.floor(cell / game.settings.width);
+    const mine = ended && game.board?.mines[cell] === true;
+    const wrong = ended && mark === MARKS.flag && !mine;
+    const clue = mark === MARKS.open ? game.board?.clues[cell] ?? 0 : 0;
+    const kind = cell === game.exploded ? "exploded" : mine ? "mine" : wrong ? "wrong" : mark;
+    const text = mine ? "✹" : wrong ? "×" : mark === MARKS.flag ? options.pieces === "stones" ? "●" : options.pieces === "flowers" ? "✿" : "⚑"
+      : mark === MARKS.question ? "?" : mark === MARKS.open && clue > 0 ? String(clue) : "";
+    const description = mine ? say.mine : wrong ? say.wrong : mark === MARKS.open ? clue === 0 ? say.empty : `${clue}` : say[mark];
+    return [{ cell, x: col + (hex ? row / 2 : 0), y: row * (hex ? .866 : 1), width: 1, height: hex ? 1.155 : 1,
+      label: `${row + 1}, ${col + 1}: ${description}`, text, kind, hint: options.hint === cell }];
+  });
+  return { width, height, cells };
+}

package/src/element-define.ts

@@ -0,0 +1,2 @@
+import { defineJirai } from "./element.ts";
+if (typeof customElements !== "undefined") defineJirai();

package/src/element.ts

@@ -0,0 +1,24 @@
+import { DEFAULT_SETTINGS } from "./jirai.constants.ts";
+import { mountJirai } from "./mount.ts";
+import type { Grid, Language, Material, Pieces, Settings } from "./jirai.types.ts";
+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;
+export class JiraiElement extends ElementBase {
+  private mounted: JiraiMount | null = null;
+  static observedAttributes = ["width", "height", "mines", "seed", "grid", "shape", "no-guess", "material", "pieces", "lang"];
+  connectedCallback(): void { this.mount(); }
+  disconnectedCallback(): void { this.mounted?.destroy(); this.mounted = null; }
+  attributeChangedCallback(): void { if (this.isConnected) this.mount(); }
+  private mount(): void {
+    this.mounted?.destroy(); this.mounted = null;
+    try {
+      this.mounted = mountJirai(this, {
+        settings: { ...DEFAULT_SETTINGS, width: Number(this.getAttribute("width") ?? DEFAULT_SETTINGS.width), height: Number(this.getAttribute("height") ?? DEFAULT_SETTINGS.height), mines: Number(this.getAttribute("mines") ?? DEFAULT_SETTINGS.mines), seed: Number(this.getAttribute("seed") ?? DEFAULT_SETTINGS.seed), shape: (this.getAttribute("shape") ?? "rectangle") as Settings["shape"], grid: (this.getAttribute("grid") ?? "square") as Grid, noGuess: this.getAttribute("no-guess") !== "false" },
+        material: (this.getAttribute("material") ?? "ivory") as Material, pieces: (this.getAttribute("pieces") ?? "flags") as Pieces, language: (this.getAttribute("lang") ?? "en") as Language,
+      });
+    } catch (error) { this.dispatchEvent(new CustomEvent("jirai-error", { detail: error })); }
+  }
+}
+export function defineJirai(registry: CustomElementRegistry = customElements): void { if (!registry.get("jirai-board")) registry.define("jirai-board", JiraiElement); }

package/src/enumerate.ts

@@ -0,0 +1,60 @@
+import { ENUMERATION_CELLS, ENUMERATION_NODES } from "./jirai.constants.ts";
+import type { Constraint, Deduction } from "./jirai.types.ts";
+
+/**
+ * Exact assignments within a small connected frontier. If the work budget is
+ * reached, none of the partial search is evidence: it returns no deductions.
+ */
+export function enumerateForced(constraints: readonly Constraint[]): Deduction {
+  const empty: Deduction = { safe: [], mines: [], reason: "none", sources: [], contradiction: false };
+  const remaining = new Set(constraints.flatMap((c) => [...c.cells]));
+  const safe: number[] = [], mines: number[] = [], sources = new Set<number>();
+  while (remaining.size > 0) {
+    const component = new Set<number>([remaining.values().next().value!]);
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const c of constraints) {
+        if (!c.cells.some((cell) => component.has(cell))) continue;
+        for (const cell of c.cells) if (!component.has(cell)) { component.add(cell); grew = true; }
+      }
+    }
+    for (const cell of component) remaining.delete(cell);
+    if (component.size > ENUMERATION_CELLS) continue;
+    const cells = [...component];
+    const relevant = constraints.filter((c) => c.cells.some((cell) => component.has(cell)));
+    const positions = relevant.map((c) => c.cells.map((cell) => cells.indexOf(cell)));
+    const assigned = new Int8Array(cells.length).fill(-1);
+    const seenMine = new Uint8Array(cells.length), seenSafe = new Uint8Array(cells.length);
+    let nodes = 0, solutions = 0, stopped = false;
+    function visit(at: number): void {
+      nodes += 1;
+      if (nodes > ENUMERATION_NODES) { stopped = true; return; }
+      for (let i = 0; i < relevant.length; i += 1) {
+        let filled = 0, unknown = 0;
+        for (const p of positions[i]!) {
+          if (assigned[p] === -1) unknown += 1;
+          else filled += assigned[p]!;
+        }
+        if (filled > relevant[i]!.mines || filled + unknown < relevant[i]!.mines) return;
+      }
+      if (at === cells.length) {
+        solutions += 1;
+        for (let i = 0; i < cells.length; i += 1) (assigned[i] === 1 ? seenMine : seenSafe)[i] = 1;
+        return;
+      }
+      assigned[at] = 0; visit(at + 1);
+      if (!stopped) { assigned[at] = 1; visit(at + 1); }
+      assigned[at] = -1;
+    }
+    visit(0);
+    if (stopped) continue;
+    if (solutions === 0) return { ...empty, contradiction: true };
+    for (let i = 0; i < cells.length; i += 1) {
+      if (!seenMine[i]) safe.push(cells[i]!);
+      if (!seenSafe[i]) mines.push(cells[i]!);
+    }
+    if (safe.length || mines.length) for (const c of relevant) for (const source of c.sources) sources.add(source);
+  }
+  return { ...empty, safe, mines, sources: [...sources], reason: safe.length || mines.length ? "enumeration" : "none" };
+}

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); }
+  }
+}