@my-games/sudoku-core 0.0.0 → 0.1.0

package/src/solver.ts

@@ -0,0 +1,95 @@
+import { candidates, cellAt, cloneGrid, hasConflict, setCell } from './board';
+import type { Digit, Grid } from './types';
+
+/**
+ * 数独回溯求解器（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: Grid): { row: number; col: number; cands: Digit[] } | null {
+  let best: { row: number; col: number; cands: Digit[] } | null = 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; // 死格 → 由调用方据 filled 判定失败
+      if (!best || cands.length < best.cands.length) {
+        best = { row: r, col: c, cands };
+        if (cands.length === 1) return best; // 已是最优，提前收敛
+      }
+    }
+  }
+  return best;
+}
+
+/** 是否已无空格。 */
+function isComplete(grid: Grid): boolean {
+  for (const row of grid) {
+    for (const v of row) if (v === 0) return false;
+  }
+  return true;
+}
+
+/** 原地回溯填充工作副本；成功返回 true（grid 被填满），失败返回 false 并复原。 */
+function fillInPlace(grid: Grid): boolean {
+  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。
+ * 不修改入参。
+ */
+export function solve(grid: Grid): Grid | null {
+  if (hasConflict(grid)) return null; // 题面自身已矛盾 → 无合法解
+  const work = cloneGrid(grid);
+  return fillInPlace(work) ? work : null;
+}
+
+/**
+ * 统计解个数，最多数到 `limit` 即早停（默认 2）。
+ * 用于唯一性判定：`countSolutions(p) === 1` 表示唯一解。
+ * 不修改入参。`limit < 1` 视为 1；题面已冲突则返回 0。
+ */
+export function countSolutions(grid: Grid, limit = 2): number {
+  if (hasConflict(grid)) return 0;
+  const cap = Math.max(1, limit);
+  const work = cloneGrid(grid);
+  let solutions = 0;
+
+  const rec = (): void => {
+    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;
+}

package/src/storage.ts

@@ -0,0 +1,115 @@
+import type { BestTimes, Difficulty, SaveStorage, SerializedSave } from './types';
+
+/**
+ * 存档与最佳用时持久化。
+ *
+ * 版本策略：读到的 version ≠ SAVE_VERSION 时，`isSerializedSave` 守卫失败 →
+ * 上层丢弃并开新局。目前仅 v1。
+ *
+ * best 存的是 `BestTimes`（每个难度历史最佳用时秒数，null = 未通关），
+ * 以 JSON 落在单个 bestKey 下，读回时补全缺失难度为 null。
+ */
+export const SAVE_VERSION = 1 as const;
+export const DEFAULT_SAVE_KEY = 'game-sudoku:save';
+export const DEFAULT_BEST_KEY = 'game-sudoku:best';
+
+const DIFFICULTIES: readonly Difficulty[] = ['easy', 'medium', 'hard'];
+
+function isDifficulty(x: unknown): x is Difficulty {
+  return typeof x === 'string' && (DIFFICULTIES as readonly string[]).includes(x);
+}
+
+/** 9×9 的二维数组守卫（浅校验行数与每行长度）。 */
+function isGridLike(x: unknown): boolean {
+  return (
+    Array.isArray(x) &&
+    x.length === 9 &&
+    x.every((row) => Array.isArray(row) && row.length === 9)
+  );
+}
+
+/** 粗粒度结构守卫：只保证关键字段形状，深层值由 Sudoku 载入时再防御。 */
+export function isSerializedSave(x: unknown): x is SerializedSave {
+  if (typeof x !== 'object' || x === null) return false;
+  const o = x as Record<string, unknown>;
+  return (
+    o['version'] === SAVE_VERSION &&
+    isDifficulty(o['difficulty']) &&
+    isGridLike(o['puzzle']) &&
+    isGridLike(o['solution']) &&
+    isGridLike(o['grid']) &&
+    (o['status'] === 'playing' || o['status'] === 'won')
+  );
+}
+
+export function loadSave(storage: SaveStorage | null, key: string): SerializedSave | null {
+  if (!storage) return null;
+  const raw = storage.getItem(key);
+  if (!raw) return null;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isSerializedSave(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeSave(storage: SaveStorage | null, key: string, save: SerializedSave): void {
+  if (!storage) return;
+  try {
+    storage.setItem(key, JSON.stringify(save));
+  } catch {
+    /* quota / 隐私模式静默忽略；不阻断游戏 */
+  }
+}
+
+export function clearSave(storage: SaveStorage | null, key: string): void {
+  if (!storage) return;
+  try {
+    storage.removeItem(key);
+  } catch {
+    /* ignore */
+  }
+}
+
+/** 空的 BestTimes（全 null）。 */
+export function emptyBestTimes(): BestTimes {
+  return { easy: null, medium: null, hard: null };
+}
+
+/** 读回 BestTimes；损坏/缺失字段回落为 null。 */
+export function loadBest(storage: SaveStorage | null, key: string): BestTimes {
+  const result = emptyBestTimes();
+  if (!storage) return result;
+  const raw = storage.getItem(key);
+  if (!raw) return result;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed === 'object' && parsed !== null) {
+      const o = parsed as Record<string, unknown>;
+      for (const d of DIFFICULTIES) {
+        const v = o[d];
+        if (typeof v === 'number' && Number.isFinite(v) && v >= 0) result[d] = Math.floor(v);
+      }
+    }
+  } catch {
+    /* 回落全 null */
+  }
+  return result;
+}
+
+export function writeBest(storage: SaveStorage | null, key: string, best: BestTimes): void {
+  if (!storage) return;
+  try {
+    storage.setItem(key, JSON.stringify(best));
+  } catch {
+    /* ignore */
+  }
+}
+
+/** 浏览器默认 Storage；无 DOM 环境返回 null，让 core 在 Node 也能跑。 */
+export function tryGetGlobalStorage(): SaveStorage | null {
+  if (typeof globalThis === 'undefined') return null;
+  const s = (globalThis as { localStorage?: SaveStorage }).localStorage;
+  return s ?? null;
+}

package/src/style.css

@@ -1,17 +1,375 @@
-/*
- * @my-games/sudoku-core —— 0.0.0 占位样式表（单数命名 ./style.css）。
+/**
+ * game-sudoku 通用样式表（单数命名：`./style.css`）。
  *
- * 空骨架阶段只放最小基类，保证三包各自构建能产出非空 dist/index.css
- * （verify:dist 守卫要求 vue/react 的 index.css 存在且非 0 字节）。
- * 真实棋盘样式（3×3 宫格布局、题面/用户/冲突配色、铅笔笔记迷你格）随引擎补入。
+ * 由 `@my-games/sudoku-core/style.css` 暴露，Vue / React 适配器都直接 import 这一份，
+ * 保持视觉一致（避免两包各自漂移）。
+ *
+ * 关键布局：棋盘是 3×3 的「宫」网格（.game-sudoku-box 各含 3×3 共 9 格）。
+ * 宫之间的粗缝（box 背景透出 strong line 色）天然构成九宫分隔线，宫之间用 box-gap、
+ * 宫内用 cell-gap 两级间距即可，无需 nth-child 取模去判边界。
+ *
+ * 约定：
+ * - 数字配色区分「题面给定」(深色加粗) 与「玩家填入」(蓝色)；冲突格红底。
+ * - 选中格高亮 + 同数/同行列宫淡色提示；空格用 .cell-notes 3×3 迷你格画铅笔标记。
+ * - 尺寸自适应：容器宽度决定一切，clamp() 缩放，320px～520px 视觉合理。
+ * - prefers-reduced-motion 下关过渡/动画。
  */
 
 .game-sudoku {
+  --board-size: min(92vw, 460px);
+  --box-gap: 3px;
+  --cell-gap: 1px;
+  --radius: clamp(4px, 1.2vw, 10px);
+  --line-strong: #3b4a5a;
+  --line-soft: #93a3b3;
+  --cell-bg: #ffffff;
+  --text-given: #1f2d3d;
+  --text-user: #1c63b5;
+  --text-muted: #8a99a8;
+  --hl-selected: #cfe3ff;
+  --hl-peer: #eef4fb;
+  --hl-same: #d7e9ff;
+  --bad: #ffd7d7;
+  --bad-text: #b4232a;
+  --accent: #1c63b5;
+  --accent-dark: #144d8f;
+
   display: inline-flex;
   flex-direction: column;
-  gap: 8px;
-  font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
-  color: #1f2d3d;
+  gap: 10px;
+  font-family: 'Helvetica Neue', 'Segoe UI', system-ui, -apple-system, sans-serif;
+  color: var(--text-given);
   user-select: none;
   -webkit-tap-highlight-color: transparent;
 }
+
+.game-sudoku-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 10px;
+  width: var(--board-size);
+  max-width: 92vw;
+}
+
+.game-sudoku-title {
+  margin: 0;
+  font-size: clamp(24px, 7vw, 38px);
+  font-weight: 800;
+  letter-spacing: -0.5px;
+}
+
+.game-sudoku-title .subtitle {
+  display: block;
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0;
+  color: var(--text-muted);
+}
+
+.game-sudoku-stats {
+  display: flex;
+  gap: 6px;
+}
+
+.game-sudoku-stat {
+  position: relative;
+  min-width: 66px;
+  padding: 5px 10px 7px;
+  border-radius: var(--radius);
+  background: var(--line-strong);
+  color: #fff;
+  text-align: center;
+  font-variant-numeric: tabular-nums;
+}
+
+.game-sudoku-stat .label {
+  display: block;
+  font-size: 10px;
+  letter-spacing: 1px;
+  text-transform: uppercase;
+  opacity: 0.85;
+}
+
+.game-sudoku-stat .value {
+  display: block;
+  font-size: 18px;
+  font-weight: 700;
+  line-height: 1.2;
+}
+
+.game-sudoku-stat.is-danger .value {
+  color: #ffb3b3;
+}
+
+.game-sudoku-toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  width: var(--board-size);
+  max-width: 92vw;
+  flex-wrap: wrap;
+}
+
+.game-sudoku-difficulty {
+  display: inline-flex;
+  gap: 4px;
+}
+
+.game-sudoku-chip {
+  padding: 6px 12px;
+  border: 1px solid var(--line-soft);
+  border-radius: 999px;
+  background: #fff;
+  color: var(--text-given);
+  font: inherit;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+}
+
+.game-sudoku-chip.is-active {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: #fff;
+}
+
+.game-sudoku-chip:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.game-sudoku-actions {
+  display: flex;
+  gap: 6px;
+  flex-wrap: wrap;
+}
+
+.game-sudoku-button {
+  padding: 8px 12px;
+  border: 0;
+  border-radius: var(--radius);
+  background: #e7edf3;
+  color: var(--text-given);
+  font: inherit;
+  font-weight: 700;
+  font-size: 13px;
+  cursor: pointer;
+  transition: background 120ms, transform 80ms;
+}
+
+.game-sudoku-button:hover:not(:disabled) {
+  background: #d7e2ec;
+}
+
+.game-sudoku-button:active:not(:disabled) {
+  transform: translateY(1px);
+}
+
+.game-sudoku-button:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+.game-sudoku-button.is-primary {
+  background: var(--accent);
+  color: #fff;
+}
+
+.game-sudoku-button.is-primary:hover:not(:disabled) {
+  background: var(--accent-dark);
+}
+
+.game-sudoku-button.is-toggled {
+  background: var(--accent-dark);
+  color: #fff;
+}
+
+.game-sudoku-board {
+  position: relative;
+  width: var(--board-size);
+  max-width: 92vw;
+  padding: var(--box-gap);
+  border-radius: var(--radius);
+  background: var(--line-strong);
+  outline: none;
+  box-sizing: content-box;
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  grid-template-rows: repeat(3, 1fr);
+  gap: var(--box-gap);
+  aspect-ratio: 1;
+}
+
+.game-sudoku-board:focus-visible {
+  box-shadow: 0 0 0 3px rgba(28, 99, 181, 0.4);
+}
+
+.game-sudoku-box {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  grid-template-rows: repeat(3, 1fr);
+  gap: var(--cell-gap);
+  background: var(--line-soft);
+  border-radius: 3px;
+  overflow: hidden;
+}
+
+.game-sudoku-cell {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--cell-bg);
+  font-weight: 500;
+  font-size: clamp(15px, 4.6vw, 26px);
+  line-height: 1;
+  cursor: pointer;
+  aspect-ratio: 1;
+}
+
+.game-sudoku-cell.is-given {
+  color: var(--text-given);
+  font-weight: 800;
+}
+
+.game-sudoku-cell.is-user {
+  color: var(--text-user);
+}
+
+.game-sudoku-cell.is-peer {
+  background: var(--hl-peer);
+}
+
+.game-sudoku-cell.is-same {
+  background: var(--hl-same);
+}
+
+.game-sudoku-cell.is-selected {
+  background: var(--hl-selected);
+}
+
+.game-sudoku-cell.is-conflict {
+  background: var(--bad);
+  color: var(--bad-text);
+}
+
+.game-sudoku-cell.is-hint {
+  color: var(--accent-dark);
+}
+
+.cell-notes {
+  position: absolute;
+  inset: 2px;
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  grid-template-rows: repeat(3, 1fr);
+  align-items: center;
+  justify-items: center;
+  font-size: clamp(7px, 1.8vw, 11px);
+  font-weight: 600;
+  color: var(--text-muted);
+  pointer-events: none;
+}
+
+.game-sudoku-pad {
+  display: grid;
+  grid-template-columns: repeat(9, 1fr);
+  gap: 6px;
+  width: var(--board-size);
+  max-width: 92vw;
+}
+
+.game-sudoku-pad button {
+  padding: 10px 0;
+  border: 0;
+  border-radius: var(--radius);
+  background: #eef3f8;
+  color: var(--text-user);
+  font: inherit;
+  font-weight: 700;
+  font-size: clamp(16px, 4vw, 22px);
+  cursor: pointer;
+}
+
+.game-sudoku-pad button:hover:not(:disabled) {
+  background: #dfeaf5;
+}
+
+.game-sudoku-pad button:disabled {
+  opacity: 0.35;
+  cursor: not-allowed;
+}
+
+.game-sudoku-pad .is-active-mode {
+  background: var(--accent);
+  color: #fff;
+}
+
+.game-sudoku-overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+  border-radius: var(--radius);
+  background: rgba(255, 255, 255, 0.86);
+  color: var(--text-given);
+  text-align: center;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 220ms ease-in;
+  z-index: 10;
+}
+
+.game-sudoku-overlay.is-visible {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.game-sudoku-overlay h2 {
+  margin: 0;
+  font-size: clamp(26px, 7vw, 40px);
+  font-weight: 800;
+  color: var(--accent-dark);
+}
+
+.game-sudoku-overlay .meta {
+  font-size: 14px;
+  color: var(--text-muted);
+}
+
+.game-sudoku-overlay .row {
+  display: flex;
+  gap: 8px;
+}
+
+.game-sudoku-desc {
+  margin: 0;
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--text-muted);
+}
+
+@keyframes game-sudoku-pop {
+  0% { transform: scale(1); }
+  50% { transform: scale(1.18); }
+  100% { transform: scale(1); }
+}
+
+.game-sudoku-cell.is-pop {
+  animation: game-sudoku-pop 200ms ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .game-sudoku-button,
+  .game-sudoku-overlay {
+    transition: none;
+  }
+  .game-sudoku-cell.is-pop {
+    animation: none;
+  }
+}