@my-games/sudoku-core 0.0.0 → 0.1.0

package/dist/index.js

@@ -1,19 +1,792 @@
-// src/index.ts
+// src/board.ts
 /**
-* @my-games/sudoku-core —— `0.0.0` 占位实现。
+* 纯函数棋盘工具：只用 `Grid`（`Cell[][]`，0 = 空），不涉及对局可变态。
 *
-* 这是一个「空包」骨架：目的仅是把 monorepo 的
-* `build → verify:dist → typecheck → test` 门禁与 npm Trusted Publisher 链路跑通，
-* 好让首版（可信发布者无法发某包的第一个版本）能先手工种进 registry。
+* 设计原则：所有「产出新棋盘」的函数都返回新数组，不原地修改输入。
+* solver / generator / Sudoku 类都建立在这套底层原语上。
 *
-* 真实数独引擎 —— 棋盘校验、回溯求解器、唯一解题生成、`Sudoku` 状态机
-* （选格/填数/擦除/笔记/提示/撤销/计时）、注入式存档与最佳用时 —— 已在占位包
-* 发布前按同一三层结构写好并暂存，待 `0.0.0` 上线后作为后续提交补回。
+* 严格模式（noUncheckedIndexedAccess）：读取一律走 `cellAt`（越界/空返回 0），
+* 派生 9×9 结构时用 `makeMask` / `setAt` 保证行存在后再写下标。
 */
-/** 包标识占位。 */
-var SUDOKU_PACKAGE = "sudoku-core";
-/** 占位版本，与 package.json 的 version 对齐，便于确认发的是 stage 包。 */
-var SUDOKU_STAGE = "0.0.0";
-export { SUDOKU_PACKAGE, SUDOKU_STAGE };
+/** 数独边长（标准 9×9）。 */
+var SIZE = 9;
+/** 宫的边长（3×3 宫，共 9 宫）。 */
+var BOX = 3;
+/** 数字 1..9 常量表（升序）。 */
+var DIGITS = [
+	1,
+	2,
+	3,
+	4,
+	5,
+	6,
+	7,
+	8,
+	9
+];
+/** 生成 SIZE×SIZE 全 0 空棋盘。 */
+function createEmptyGrid() {
+	return Array.from({ length: 9 }, () => Array(9).fill(0));
+}
+/** 深拷贝棋盘。 */
+function cloneGrid(grid) {
+	return grid.map((row) => row.slice());
+}
+/** 生成 SIZE×SIZE 掩码，初值由 `fill` 决定。 */
+function makeMask(fill) {
+	return Array.from({ length: 9 }, () => Array(9).fill(fill));
+}
+/** 安全读取：越界返回 0。 */
+function cellAt(grid, row, col) {
+	return grid[row]?.[col] ?? 0;
+}
+/** 安全写入：仅在行存在时写入（返回同一引用，供链式）。 */
+function setCell(grid, row, col, value) {
+	const line = grid[row];
+	if (line) line[col] = value;
+	return grid;
+}
+/** 返回把 (row,col) 设为 value 后的新棋盘（不改动入参）。 */
+function withCell(grid, row, col, value) {
+	return setCell(cloneGrid(grid), row, col, value);
+}
+/** (row,col) 所属宫的左上角坐标。 */
+function boxOrigin(row, col) {
+	return {
+		r: Math.floor(row / 3) * 3,
+		c: Math.floor(col / 3) * 3
+	};
+}
+/** 与 (row,col) 同处一行、一列、一宫（不含自身）的所有坐标，去重后共 20 个。 */
+function peers(row, col) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	const push = (r, c) => {
+		if (r === row && c === col) return;
+		const key = r * 9 + c;
+		if (seen.has(key)) return;
+		seen.add(key);
+		out.push([r, c]);
+	};
+	for (let i = 0; i < 9; i++) {
+		push(row, i);
+		push(i, col);
+	}
+	const { r, c } = boxOrigin(row, col);
+	for (let dr = 0; dr < 3; dr++) for (let dc = 0; dc < 3; dc++) push(r + dr, c + dc);
+	return out;
+}
+/**
+* 数字 digit 能否放到 (row,col)：检查所有 peer 是否已占用同值。
+* 不关心 (row,col) 当前值（用于「换个值是否合法」判断）。
+*/
+function isSafe(grid, row, col, digit) {
+	for (const [pr, pc] of peers(row, col)) if (cellAt(grid, pr, pc) === digit) return false;
+	return true;
+}
+/** 空格 (row,col) 的所有合法候选数字；非空格返回 []。 */
+function candidates(grid, row, col) {
+	if (cellAt(grid, row, col) !== 0) return [];
+	const out = [];
+	for (const d of DIGITS) if (isSafe(grid, row, col, d)) out.push(d);
+	return out;
+}
+/** 所有空格坐标（行优先）。 */
+function emptyCells(grid) {
+	const out = [];
+	for (let r = 0; r < 9; r++) for (let c = 0; c < 9; c++) if (cellAt(grid, r, c) === 0) out.push([r, c]);
+	return out;
+}
+/** 是否填满（无 0）。 */
+function isFull(grid) {
+	for (let r = 0; r < 9; r++) for (let c = 0; c < 9; c++) if (cellAt(grid, r, c) === 0) return false;
+	return true;
+}
+/**
+* 计算冲突掩码：某格为非 0 且与任一 peer 同值 → true。
+* 供 UI 标红「当前矛盾」的格，允许存在空格（部分填写）。
+*/
+function findConflicts(grid) {
+	const mask = makeMask(false);
+	for (let r = 0; r < 9; r++) for (let c = 0; c < 9; c++) {
+		const v = cellAt(grid, r, c);
+		if (v === 0) continue;
+		for (const [pr, pc] of peers(r, c)) if (cellAt(grid, pr, pc) === v) {
+			const line = mask[r];
+			if (line) line[c] = true;
+			break;
+		}
+	}
+	return mask;
+}
+/** 是否存在任意冲突（有重复）。 */
+function hasConflict(grid) {
+	for (const row of findConflicts(grid)) for (const v of row) if (v) return true;
+	return false;
+}
+/**
+* 是否为「合法完成盘」：填满且无冲突。
+* 等价于每行/列/宫都是 1..9 的一个排列。
+*/
+function isSolved(grid) {
+	return isFull(grid) && !hasConflict(grid);
+}
+/** 棋盘相等（逐格比较）。 */
+function gridsEqual(a, b) {
+	for (let r = 0; r < 9; r++) for (let c = 0; c < 9; c++) if (cellAt(a, r, c) !== cellAt(b, r, c)) return false;
+	return true;
+}
+/** 数非空格数量（题面线索数）。 */
+function countFilled(grid) {
+	let n = 0;
+	for (let r = 0; r < 9; r++) for (let c = 0; c < 9; c++) if (cellAt(grid, r, c) !== 0) n++;
+	return n;
+}
+// src/solver.ts
+/**
+* 数独回溯求解器（MRV 启发式）+ 解个数统计。
+*
+* - `solve`：给定（可能不完整的）合法棋盘，返回一个完整解的副本；无解返回 null。
+* - `countSolutions(grid, limit)`：统计该棋盘有多少个不同完整解，最多数到 `limit`
+*   就早停。生成器用 `limit = 2` 判定「唯一解」（返回 1 → 唯一；≥2 → 多解）。
+*
+* MRV（Minimum Remaining Values）：每步优先填「候选数最少」的空格，
+* 一旦某空格候选为 0 立即回溯。标准 9×9 题在毫秒级完成，纯同步、无副作用。
+*
+* 内部对「工作副本」做原地 try/untry（backtracking 需要），但对外一律
+* 先 `cloneGrid`，绝不改动调用者传入的棋盘。
+*/
+/** 在 grid 上找候选最少的空格；若填满返回 null；若发现死格（0 候选）返回 { dead:true }。 */
+function pickCell(grid) {
+	let best = null;
+	for (let r = 0; r < grid.length; r++) for (let c = 0; c < (grid[r]?.length ?? 0); c++) {
+		if (cellAt(grid, r, c) !== 0) continue;
+		const cands = candidates(grid, r, c);
+		if (cands.length === 0) return null;
+		if (!best || cands.length < best.cands.length) {
+			best = {
+				row: r,
+				col: c,
+				cands
+			};
+			if (cands.length === 1) return best;
+		}
+	}
+	return best;
+}
+/** 是否已无空格。 */
+function isComplete(grid) {
+	for (const row of grid) for (const v of row) if (v === 0) return false;
+	return true;
+}
+/** 原地回溯填充工作副本；成功返回 true（grid 被填满），失败返回 false 并复原。 */
+function fillInPlace(grid) {
+	if (isComplete(grid)) return true;
+	const cell = pickCell(grid);
+	if (!cell) return false;
+	for (const d of cell.cands) {
+		setCell(grid, cell.row, cell.col, d);
+		if (fillInPlace(grid)) return true;
+		setCell(grid, cell.row, cell.col, 0);
+	}
+	return false;
+}
+/**
+* 求解：返回完整解的新棋盘；若初始棋盘非法（已冲突）/无解返回 null。
+* 不修改入参。
+*/
+function solve(grid) {
+	if (hasConflict(grid)) return null;
+	const work = cloneGrid(grid);
+	return fillInPlace(work) ? work : null;
+}
+/**
+* 统计解个数，最多数到 `limit` 即早停（默认 2）。
+* 用于唯一性判定：`countSolutions(p) === 1` 表示唯一解。
+* 不修改入参。`limit < 1` 视为 1；题面已冲突则返回 0。
+*/
+function countSolutions(grid, limit = 2) {
+	if (hasConflict(grid)) return 0;
+	const cap = Math.max(1, limit);
+	const work = cloneGrid(grid);
+	let solutions = 0;
+	const rec = () => {
+		if (solutions >= cap) return;
+		if (isComplete(work)) {
+			solutions++;
+			return;
+		}
+		const cell = pickCell(work);
+		if (!cell) return;
+		for (const d of cell.cands) {
+			setCell(work, cell.row, cell.col, d);
+			rec();
+			setCell(work, cell.row, cell.col, 0);
+			if (solutions >= cap) return;
+		}
+	};
+	rec();
+	return solutions;
+}
+// src/generator.ts
+/**
+* 数独生成器：产出「有唯一解」的题目。
+*
+* 流程：
+* 1. `generateFullGrid` —— 随机回溯填满一张合法终盘（作为 solution）。
+* 2. `digHoles` —— 以随机顺序尝试把格子挖空；每挖一格前用 `countSolutions(limit=2)`
+*    校验：挖掉后仍「唯一解」才保留，否则回填。挖到目标线索数或无格可挖为止。
+*
+* 这样产出的 puzzle 保证唯一解，且 puzzle ⊂ solution（挖掉的都是解里可推出来的格）。
+* rng 注入保证单测可复现；默认 `Math.random`。
+*/
+/** 各难度目标线索数（题面给定数字个数）。实际可能因唯一性约束略多。 */
+var TARGET_CLUES = {
+	easy: 45,
+	medium: 35,
+	hard: 27
+};
+/** Fisher–Yates 洗牌（返回新数组，用注入 rng）。 */
+function shuffle(input, rng) {
+	const arr = input.slice();
+	for (let i = arr.length - 1; i > 0; i--) {
+		const j = Math.floor(rng() * (i + 1));
+		const tmp = arr[i];
+		const a = arr[j];
+		if (tmp !== void 0 && a !== void 0) {
+			arr[i] = a;
+			arr[j] = tmp;
+		}
+	}
+	return arr;
+}
+/** 从 pos 起原地回溯填满 grid（每格用随机顺序的合法数字）。 */
+function fillFully(grid, pos, rng) {
+	if (pos >= grid.length * grid.length) return true;
+	const row = Math.floor(pos / grid.length);
+	const col = pos % grid.length;
+	if (cellAt(grid, row, col) !== 0) return fillFully(grid, pos + 1, rng);
+	for (const d of shuffle(DIGITS, rng)) if (isSafe(grid, row, col, d)) {
+		setCell(grid, row, col, d);
+		if (fillFully(grid, pos + 1, rng)) return true;
+		setCell(grid, row, col, 0);
+	}
+	return false;
+}
+/** 生成一张随机合法终盘（9×9 全填、无冲突）。 */
+function generateFullGrid(rng = Math.random) {
+	const grid = createEmptyGrid();
+	fillFully(grid, 0, rng);
+	return grid;
+}
+/**
+* 在终盘副本上随机挖洞到目标线索数，保持唯一解。
+* 返回挖洞后的题面（会修改并返回传入的 puzzle 副本，入参 solution 不动）。
+*/
+function digHoles(solution, targetClues, rng) {
+	const puzzle = solution.map((row) => row.slice());
+	const total = puzzle.length * puzzle.length;
+	const order = [];
+	for (let i = 0; i < total; i++) order.push(i);
+	const shuffled = shuffle(order, rng);
+	let clues = total;
+	for (const idx of shuffled) {
+		if (clues <= targetClues) break;
+		const r = Math.floor(idx / puzzle.length);
+		const c = idx % puzzle.length;
+		const backup = cellAt(puzzle, r, c);
+		if (backup === 0) continue;
+		setCell(puzzle, r, c, 0);
+		if (countSolutions(puzzle, 2) === 1) clues--;
+		else setCell(puzzle, r, c, backup);
+	}
+	return puzzle;
+}
+/** 生成一道指定难度、唯一解的数独题。 */
+function generatePuzzle(difficulty = "easy", rng = Math.random) {
+	const solution = generateFullGrid(rng);
+	const puzzle = digHoles(solution, TARGET_CLUES[difficulty] ?? TARGET_CLUES.easy, rng);
+	let clues = 0;
+	for (const row of puzzle) for (const v of row) if (v !== 0) clues++;
+	return {
+		puzzle,
+		solution,
+		difficulty,
+		clues
+	};
+}
+// src/storage.ts
+/**
+* 存档与最佳用时持久化。
+*
+* 版本策略：读到的 version ≠ SAVE_VERSION 时，`isSerializedSave` 守卫失败 →
+* 上层丢弃并开新局。目前仅 v1。
+*
+* best 存的是 `BestTimes`（每个难度历史最佳用时秒数，null = 未通关），
+* 以 JSON 落在单个 bestKey 下，读回时补全缺失难度为 null。
+*/
+var SAVE_VERSION = 1;
+var DEFAULT_SAVE_KEY = "game-sudoku:save";
+var DEFAULT_BEST_KEY = "game-sudoku:best";
+var DIFFICULTIES = [
+	"easy",
+	"medium",
+	"hard"
+];
+function isDifficulty(x) {
+	return typeof x === "string" && DIFFICULTIES.includes(x);
+}
+/** 9×9 的二维数组守卫（浅校验行数与每行长度）。 */
+function isGridLike(x) {
+	return Array.isArray(x) && x.length === 9 && x.every((row) => Array.isArray(row) && row.length === 9);
+}
+/** 粗粒度结构守卫：只保证关键字段形状，深层值由 Sudoku 载入时再防御。 */
+function isSerializedSave(x) {
+	if (typeof x !== "object" || x === null) return false;
+	const o = x;
+	return o["version"] === 1 && isDifficulty(o["difficulty"]) && isGridLike(o["puzzle"]) && isGridLike(o["solution"]) && isGridLike(o["grid"]) && (o["status"] === "playing" || o["status"] === "won");
+}
+function loadSave(storage, key) {
+	if (!storage) return null;
+	const raw = storage.getItem(key);
+	if (!raw) return null;
+	try {
+		const parsed = JSON.parse(raw);
+		return isSerializedSave(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+function writeSave(storage, key, save) {
+	if (!storage) return;
+	try {
+		storage.setItem(key, JSON.stringify(save));
+	} catch {}
+}
+function clearSave(storage, key) {
+	if (!storage) return;
+	try {
+		storage.removeItem(key);
+	} catch {}
+}
+/** 空的 BestTimes（全 null）。 */
+function emptyBestTimes() {
+	return {
+		easy: null,
+		medium: null,
+		hard: null
+	};
+}
+/** 读回 BestTimes；损坏/缺失字段回落为 null。 */
+function loadBest(storage, key) {
+	const result = emptyBestTimes();
+	if (!storage) return result;
+	const raw = storage.getItem(key);
+	if (!raw) return result;
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed === "object" && parsed !== null) {
+			const o = parsed;
+			for (const d of DIFFICULTIES) {
+				const v = o[d];
+				if (typeof v === "number" && Number.isFinite(v) && v >= 0) result[d] = Math.floor(v);
+			}
+		}
+	} catch {}
+	return result;
+}
+function writeBest(storage, key, best) {
+	if (!storage) return;
+	try {
+		storage.setItem(key, JSON.stringify(best));
+	} catch {}
+}
+/** 浏览器默认 Storage；无 DOM 环境返回 null，让 core 在 Node 也能跑。 */
+function tryGetGlobalStorage() {
+	if (typeof globalThis === "undefined") return null;
+	return globalThis.localStorage ?? null;
+}
+// src/game.ts
+var DEFAULT_DIFFICULTY = "easy";
+var DEFAULT_UNDO_LIMIT = 50;
+/** 深拷贝笔记网格。 */
+function cloneNotes(notes) {
+	return notes.map((row) => row.map((cell) => cell.slice()));
+}
+/** 初始化 9×9 全空笔记。 */
+function emptyNotes() {
+	return Array.from({ length: 9 }, () => Array.from({ length: 9 }, () => []));
+}
+/** 由题面推导「给定掩码」。 */
+function maskFromPuzzle(puzzle) {
+	return puzzle.map((row) => row.map((v) => v !== 0));
+}
+/** 升序去重写回某格笔记。 */
+function sortedUnique(digits) {
+	return Array.from(new Set(digits)).sort((a, b) => a - b);
+}
+/**
+* Sudoku —— 数独状态机与规则实现，与 UI 完全解耦。
+*
+* - 通过 `subscribe(fn)` 推完整 `GameState` 快照（不推 diff）；注册即收到一次。
+* - 每次改变局面的公开操作（input/erase/toggleNote/hint/newGame/undo）成功后
+*   走一次 `commit()`：写存档 + 通知订阅。`select()` 只更新选中并通知，不落盘。
+* - 谜题来源：默认按 `difficulty` 现场生成唯一解题；也可注入 `puzzle`（+可选 solution）
+*   用作固定题/测试。`newGame()` 总是重新随机生成一道。
+* - 计时：注入 `clock`（默认 Date.now）；`elapsedMs = baseMs + (clock()-origin)`，
+*   通关瞬间冻结为 `finalMs`。undo 回未到通关的快照会按当时累计值续表。
+* - 存档：注入 storage（默认尝试 globalThis.localStorage）；`best` 是分难度最佳用时。
+*/
+var Sudoku = class {
+	constructor(opts = {}) {
+		this.selected = null;
+		this.status = "playing";
+		this.hintCount = 0;
+		this.mistakeCount = 0;
+		this.moveCount = 0;
+		this.history = [];
+		this.started = false;
+		this.baseMs = 0;
+		this.origin = 0;
+		this.finalMs = 0;
+		this.listeners = /* @__PURE__ */ new Set();
+		this.notifying = false;
+		this.rng = opts.rng ?? Math.random;
+		this.clock = opts.clock ?? Date.now;
+		this.storage = opts.storage === void 0 ? tryGetGlobalStorage() : opts.storage;
+		this.saveKey = opts.saveKey ?? "game-sudoku:save";
+		this.bestKey = opts.bestKey ?? "game-sudoku:best";
+		this.undoLimit = opts.undoLimit ?? DEFAULT_UNDO_LIMIT;
+		this.difficulty = opts.difficulty ?? DEFAULT_DIFFICULTY;
+		this.best = loadBest(this.storage, this.bestKey);
+		this.fixedPuzzle = opts.puzzle ? cloneGrid(opts.puzzle) : null;
+		this.fixedSolution = opts.solution ? cloneGrid(opts.solution) : null;
+		this.puzzle = this.fixedPuzzle ?? cloneGrid(generatePuzzle(this.difficulty, this.rng).puzzle);
+		this.solution = this.deriveSolution(this.puzzle);
+		const saved = opts.freshStart ? null : loadSave(this.storage, this.saveKey);
+		if (saved && this.canReserve(saved)) this.loadFromSave(saved);
+		else this.startNewGame(this.difficulty);
+	}
+	/** 订阅状态变化，返回退订函数；注册后立刻收到一次当前快照。 */
+	subscribe(fn) {
+		this.listeners.add(fn);
+		try {
+			fn(this.getState());
+		} catch (err) {
+			console.error("[game-sudoku] listener threw on subscribe:", err);
+		}
+		return () => {
+			this.listeners.delete(fn);
+		};
+	}
+	getState() {
+		return {
+			difficulty: this.difficulty,
+			grid: cloneGrid(this.grid),
+			givenMask: this.givenMask.map((row) => row.slice()),
+			notes: cloneNotes(this.notes),
+			selected: this.selected ? { ...this.selected } : null,
+			conflicts: findConflicts(this.grid),
+			status: this.status,
+			elapsedSeconds: Math.floor(this.elapsedMs() / 1e3),
+			bestSeconds: this.best[this.difficulty],
+			hintCount: this.hintCount,
+			mistakeCount: this.mistakeCount,
+			moveCount: this.moveCount,
+			historySize: this.history.length
+		};
+	}
+	getGrid() {
+		return cloneGrid(this.grid);
+	}
+	getPuzzle() {
+		return cloneGrid(this.puzzle);
+	}
+	getSolution() {
+		return cloneGrid(this.solution);
+	}
+	canUndo() {
+		return this.history.length > 0;
+	}
+	/** 选中某格（越界则忽略）。仅更新选中并通知订阅，不写存档、不入 undo 栈。 */
+	select(row, col) {
+		if (row < 0 || row >= 9 || col < 0 || col >= 9) return;
+		if (this.selected?.row === row && this.selected?.col === col) return;
+		this.selected = {
+			row,
+			col
+		};
+		this.notify();
+	}
+	/**
+	* 在选中格填数字。题面给定格 / 已通关时忽略。
+	* 返回 true = 棋盘确有变化。填了与盘面冲突的值会计一次 mistake（仍允许填）。
+	*/
+	input(digit) {
+		if (this.status === "won") return false;
+		const sel = this.selected;
+		if (!sel) return false;
+		if (this.givenMask[sel.row]?.[sel.col]) return false;
+		if (cellAt(this.grid, sel.row, sel.col) === digit) return false;
+		this.pushHistory();
+		this.ensureStarted();
+		setCell(this.grid, sel.row, sel.col, digit);
+		const notesRow = this.notes[sel.row];
+		if (notesRow) notesRow[sel.col] = [];
+		this.moveCount++;
+		if (!isSafe(this.grid, sel.row, sel.col, digit)) this.mistakeCount++;
+		this.checkWin();
+		this.commit();
+		return true;
+	}
+	/** 擦除选中格（值与笔记一起清）。题面给定 / 已通关忽略。返回是否有变化。 */
+	erase() {
+		if (this.status === "won") return false;
+		const sel = this.selected;
+		if (!sel) return false;
+		if (this.givenMask[sel.row]?.[sel.col]) return false;
+		const hadValue = cellAt(this.grid, sel.row, sel.col) !== 0;
+		const notesRow = this.notes[sel.row];
+		const hadNotes = !!notesRow?.[sel.col]?.length;
+		if (!hadValue && !hadNotes) return false;
+		this.pushHistory();
+		setCell(this.grid, sel.row, sel.col, 0);
+		if (notesRow) notesRow[sel.col] = [];
+		if (hadValue) this.moveCount++;
+		this.commit();
+		return true;
+	}
+	/**
+	* 切换选中空格的某条铅笔笔记。仅对「非给定且当前为空」的格生效。
+	* 返回 true = 笔记集合确有变化。
+	*/
+	toggleNote(digit) {
+		if (this.status === "won") return false;
+		const sel = this.selected;
+		if (!sel) return false;
+		if (this.givenMask[sel.row]?.[sel.col]) return false;
+		if (cellAt(this.grid, sel.row, sel.col) !== 0) return false;
+		const notesRow = this.notes[sel.row];
+		if (!notesRow) return false;
+		const current = notesRow[sel.col] ?? [];
+		const has = current.includes(digit);
+		this.pushHistory();
+		notesRow[sel.col] = has ? sortedUnique(current.filter((d) => d !== digit)) : sortedUnique([...current, digit]);
+		this.commit();
+		return true;
+	}
+	/**
+	* 提示：优先填「选中的空格」，否则填第一个空格；写入解中的正确值并清该格笔记。
+	* 返回 true = 确有一格被填。计一次 hint（不单独计 mistake）。
+	*/
+	hint() {
+		if (this.status === "won") return false;
+		const target = this.pickHintTarget();
+		if (!target) return false;
+		const answer = cellAt(this.solution, target.row, target.col);
+		if (answer === 0) return false;
+		this.pushHistory();
+		this.ensureStarted();
+		setCell(this.grid, target.row, target.col, answer);
+		const notesRow = this.notes[target.row];
+		if (notesRow) notesRow[target.col] = [];
+		this.selected = target;
+		this.hintCount++;
+		this.moveCount++;
+		this.checkWin();
+		this.commit();
+		return true;
+	}
+	/**
+	* 开启新局：随机生成指定难度（默认沿用当前难度）的唯一解题，清空局面与历史，
+	* 计时归零，best 保留。会清除旧存档并落一份新局存档。
+	*/
+	newGame(difficulty = this.difficulty) {
+		this.startNewGame(difficulty);
+		this.commit();
+	}
+	/** 撤销一步；返回是否成功。 */
+	undo() {
+		const s = this.history.pop();
+		if (!s) return false;
+		this.restoreSnapshot(s);
+		this.commit();
+		return true;
+	}
+	/** 清除当前存档（不影响 best）。 */
+	clearSaved() {
+		clearSave(this.storage, this.saveKey);
+	}
+	/** 由（部分）题面推导完整解：优先用注入的 solution，否则用 solve。 */
+	deriveSolution(puzzle) {
+		if (this.fixedSolution && !hasConflict(puzzle) && gridsCompatible(puzzle, this.fixedSolution)) return cloneGrid(this.fixedSolution);
+		return solve(puzzle) ?? cloneGrid(puzzle);
+	}
+	/** 存档是否可续用：同难度、同题面（防切难度/换题后串档）。 */
+	canReserve(save) {
+		if (save.difficulty !== this.difficulty) return false;
+		if (this.fixedPuzzle) return gridsCompatible(this.fixedPuzzle, save.puzzle);
+		return true;
+	}
+	startNewGame(difficulty) {
+		this.difficulty = difficulty;
+		if (this.fixedPuzzle) {
+			this.puzzle = cloneGrid(this.fixedPuzzle);
+			this.solution = this.deriveSolution(this.puzzle);
+		} else {
+			const gen = generatePuzzle(difficulty, this.rng);
+			this.puzzle = gen.puzzle;
+			this.solution = gen.solution;
+		}
+		this.givenMask = maskFromPuzzle(this.puzzle);
+		this.grid = cloneGrid(this.puzzle);
+		this.notes = emptyNotes();
+		this.selected = firstEmpty(this.grid);
+		this.status = "playing";
+		this.hintCount = 0;
+		this.mistakeCount = 0;
+		this.moveCount = 0;
+		this.history = [];
+		this.started = false;
+		this.baseMs = 0;
+		this.finalMs = 0;
+		this.origin = this.clock();
+		this.clearSaved();
+	}
+	/** 首次填充（input/hint）时懒起表；未起表前 elapsedMs 恒 0。 */
+	ensureStarted() {
+		if (this.started) return;
+		this.started = true;
+		this.baseMs = 0;
+		this.origin = this.clock();
+	}
+	elapsedMs() {
+		if (this.status === "won") return this.finalMs;
+		if (!this.started) return 0;
+		return this.baseMs + (this.clock() - this.origin);
+	}
+	checkWin() {
+		if (this.status !== "playing") return;
+		for (let r = 0; r < 9; r++) for (let c = 0; c < 9; c++) if (cellAt(this.grid, r, c) === 0) return;
+		for (const row of findConflicts(this.grid)) for (const v of row) if (v) return;
+		this.finalMs = this.baseMs + (this.clock() - this.origin);
+		this.status = "won";
+		const secs = Math.floor(this.finalMs / 1e3);
+		const cur = this.best[this.difficulty];
+		if (cur === null || secs < cur) {
+			this.best[this.difficulty] = secs;
+			writeBest(this.storage, this.bestKey, this.best);
+		}
+	}
+	pickHintTarget() {
+		const sel = this.selected;
+		if (sel && cellAt(this.grid, sel.row, sel.col) === 0 && !this.givenMask[sel.row]?.[sel.col]) return { ...sel };
+		return firstEmpty(this.grid);
+	}
+	pushHistory() {
+		const snap = {
+			grid: cloneGrid(this.grid),
+			notes: cloneNotes(this.notes),
+			selected: this.selected ? { ...this.selected } : null,
+			status: this.status,
+			hintCount: this.hintCount,
+			mistakeCount: this.mistakeCount,
+			moveCount: this.moveCount,
+			elapsedMs: this.elapsedMs(),
+			started: this.started
+		};
+		this.history.push(snap);
+		if (this.history.length > this.undoLimit) this.history.shift();
+	}
+	restoreSnapshot(s) {
+		this.grid = cloneGrid(s.grid);
+		this.notes = cloneNotes(s.notes);
+		this.selected = s.selected ? { ...s.selected } : null;
+		this.status = s.status;
+		this.hintCount = s.hintCount;
+		this.mistakeCount = s.mistakeCount;
+		this.moveCount = s.moveCount;
+		this.started = s.started;
+		if (s.status === "won") this.finalMs = s.elapsedMs;
+		else {
+			this.baseMs = s.elapsedMs;
+			this.origin = this.clock();
+		}
+	}
+	loadFromSave(save) {
+		this.difficulty = save.difficulty;
+		this.puzzle = cloneGrid(save.puzzle);
+		this.solution = cloneGrid(save.solution);
+		this.givenMask = maskFromPuzzle(this.puzzle);
+		this.grid = cloneGrid(save.grid);
+		this.notes = save.notes ? cloneNotes(save.notes) : emptyNotes();
+		this.status = save.status === "won" ? "won" : "playing";
+		this.hintCount = numberOr(save.hintCount, 0);
+		this.mistakeCount = numberOr(save.mistakeCount, 0);
+		this.moveCount = numberOr(save.moveCount, 0);
+		this.history = [];
+		this.selected = firstEmpty(this.grid);
+		const elapsed = numberOr(save.elapsedMs, 0);
+		this.started = this.status === "won" || this.moveCount > 0 || elapsed > 0;
+		if (this.status === "won") {
+			this.finalMs = elapsed;
+			this.baseMs = elapsed;
+			this.origin = this.clock();
+		} else {
+			this.baseMs = elapsed;
+			this.finalMs = 0;
+			this.origin = this.clock();
+		}
+	}
+	commit() {
+		writeSave(this.storage, this.saveKey, {
+			version: 1,
+			difficulty: this.difficulty,
+			puzzle: cloneGrid(this.puzzle),
+			solution: cloneGrid(this.solution),
+			grid: cloneGrid(this.grid),
+			notes: cloneNotes(this.notes),
+			status: this.status,
+			hintCount: this.hintCount,
+			mistakeCount: this.mistakeCount,
+			moveCount: this.moveCount,
+			elapsedMs: this.elapsedMs()
+		});
+		this.notify();
+	}
+	notify() {
+		if (this.notifying) return;
+		this.notifying = true;
+		try {
+			const snapshot = this.getState();
+			for (const fn of this.listeners) try {
+				fn(snapshot);
+			} catch (err) {
+				console.error("[game-sudoku] listener threw:", err);
+			}
+		} finally {
+			this.notifying = false;
+		}
+	}
+};
+/** puzzle ⊂ solution：puzzle 非 0 处 solution 必须同值。 */
+function gridsCompatible(puzzle, solution) {
+	for (let r = 0; r < puzzle.length; r++) for (let c = 0; c < (puzzle[r]?.length ?? 0); c++) {
+		const p = cellAt(puzzle, r, c);
+		if (p !== 0 && cellAt(solution, r, c) !== p) return false;
+	}
+	return true;
+}
+function firstEmpty(grid) {
+	for (let r = 0; r < 9; r++) for (let c = 0; c < 9; c++) if (cellAt(grid, r, c) === 0) return {
+		row: r,
+		col: c
+	};
+	return null;
+}
+function numberOr(x, fallback) {
+	return typeof x === "number" && Number.isFinite(x) ? x : fallback;
+}
+export { BOX, DEFAULT_BEST_KEY, DEFAULT_SAVE_KEY, DIGITS, SAVE_VERSION, SIZE, Sudoku, TARGET_CLUES, candidates, cellAt, clearSave, cloneGrid, countFilled, countSolutions, createEmptyGrid, emptyBestTimes, emptyCells, findConflicts, generateFullGrid, generatePuzzle, gridsEqual, hasConflict, isFull, isSafe, isSerializedSave, isSolved, loadBest, loadSave, makeMask, peers, setCell, solve, tryGetGlobalStorage, withCell, writeBest, writeSave };
 
 //# sourceMappingURL=index.js.map