# 多条命扫雷 · 项目契约（v2）

> **项目**：`minesweeper-lives`  
> **阶段**：第 1～5 步（骨架 + 棋盘 + 玩法，当前可玩）  
> **契约版本**：v2 · 2026-11-21  
> **文件性质**：本文件是第 2～6 步的唯一命名与接口契约。

本文件冻结以下内容：目录结构、脚本加载顺序、DOM id、全局命名空间、Config 字段、Cell / GameState / lives 数据结构、模块函数签名、彩蛋事件名与依赖边界。

后续步骤只能在**不破坏本文件**的前提下补齐实现。若确实需要改名、增删字段或更改签名，必须先修改本文件并取得确认；不得静默变更。

---

## 0. 第 1 步交付边界

本步骤只交付骨架、入口、数据结构、接口契约和静态占位渲染。

**明确不实现：**

- 随机布雷、真实棋盘生成、邻雷计算；
- 首次点击判定、首点安全保护、首点 0 格展开；
- 翻开、插旗、连开、胜负判定；
- 生命扣除、死亡、`lostHistory` 写入；
- 渲染循环、逐帧动画、Canvas 动态刷新；
- 点击/右键/难度/重开的实际输入交互；
- 任何具体彩蛋内容或自动事件派发。

当前部分函数会返回**占位值**（例如 `generateRandomBoard` 返回全非雷空棋盘、`countAdjacentMines` 返回 0），不得据此认为业务逻辑已经可用。

`index.html` 可直接双击打开，不需要构建、服务器或任何网络资源。

---

## 1. 目录结构

```text
minesweeper-lives/
├── index.html
├── styles.css
├── CONTRACTS.md
├── assets/                 # 空目录：本步骤不引入任何资源
└── js/
    ├── config.js
    ├── state.js
    ├── board.js
    ├── renderer.js
    ├── input.js
    ├── easter-eggs.js
    └── main.js
```

| 文件 | 职责 | 第 1 步状态 |
| --- | --- | --- |
| `index.html` | 静态单页入口、固定 DOM、固定脚本顺序 | 已完成 |
| `styles.css` | 静态布局与视觉样式；无动画、无外部字体 | 已完成 |
| `CONTRACTS.md` | 契约与待确认项 | 本文件 |
| `assets/` | 资源目录 | 空目录占位 |
| `js/config.js` | 创建命名空间；配置、难度、状态枚举、事件名 | 已完成 |
| `js/state.js` | GameState 容器与初始状态 | 骨架 + 浅层状态读写 |
| `js/board.js` | Cell / 棋盘数据结构与接口 | 骨架 + 空实现 |
| `js/renderer.js` | Canvas 2D 静态占位绘制 | 一次性静态渲染 |
| `js/input.js` | 输入回调绑定接口 | 仅保存引用，不注册监听器 |
| `js/easter-eggs.js` | 彩蛋注册与事件派发机制 | 机制可用，无具体彩蛋 |
| `js/main.js` | 读取 DOM、装配模块、创建初始状态、静态渲染 | 已完成 |

---

## 2. 脚本加载顺序（冻结）

`index.html` 在 `</body>` 前按以下顺序加载**普通 script**：

```html
<script src="js/config.js"></script>
<script src="js/state.js"></script>
<script src="js/board.js"></script>
<script src="js/renderer.js"></script>
<script src="js/input.js"></script>
<script src="js/easter-eggs.js"></script>
<script src="js/main.js"></script>
```

顺序编号：

1. `js/config.js`
2. `js/state.js`
3. `js/board.js`
4. `js/renderer.js`
5. `js/input.js`
6. `js/easter-eggs.js`
7. `js/main.js`

强制规则：

- 所有脚本都是**普通同步脚本**，位于 `body` 末尾；不得使用 `async`、`defer`、`type="module"`。
- 不得使用动态 `import()`、运行时脚本注入、`fetch` 加载模块、构建时注入或任何模块加载器。
- `config.js` 是唯一创建 `window.MinesweeperLives` 的模块。
- 后续模块只依赖 `window.MinesweeperLives`；如果前置模块缺失，直接抛错，不静默降级。
- `main.js` 必须最后加载，并检查全部模块是否存在。
- 为避免本地 `file://` 缓存旧脚本，`index.html` 的 `<script>` / `<link>` 可附加 `?v=` 查询串；查询串不改变加载顺序、脚本类型与执行时机。
- 因为脚本位于 `</body>` 前且同步执行，`main.js` 在文件末尾自动调用一次 `MinesweeperLives.Main.init()`；不等待异步事件。

依赖关系：

```text
config.js
  ├── state.js        （读取 Config）
  ├── board.js        （读取 Config）
  ├── renderer.js     （读取 Config）
  ├── input.js        （读取 Config）
  └── easter-eggs.js  （读取 Config / EVENTS）
main.js               （需要以上全部模块）
```

---

## 3. DOM id（冻结）

以下 id 必须存在、唯一，且不得改名或删除：

| id | 元素 | 用途 | 当前行为 |
| --- | --- | --- | --- |
| `game-canvas` | `<canvas>` | 游戏绘制画布 | 逻辑尺寸 512 × 512，由 `Main.init` 写入；已接鼠标输入 |
| `difficulty-select` | 元素（当前为 `<div>` 按钮组容器） | 难度选择 | 三个 `data-difficulty` 按钮；点击即开局或切难度 |
| `lives-value` | 元素（当前为 `<span>`） | 生命值 HUD | 与 `GameState.lives` 同步 |
| `status-value` | 元素（当前为 `<span>`） | 状态 HUD | 与 `GameState.status` 同步 |
| `remaining-value` | 元素（当前为 `<span>`） | 剩余安全格 HUD | 与 `GameState.cells` / `revealedCount` 同步 |
| `restart-button` | `<button type="button">` | 重新开始按钮 | 点击按当前难度重开 |
| `mode-select` | 元素（当前为 `<div>` 按钮组容器） | 触屏操作模式切换 | 两个 `data-mode` 按钮（`reveal` / `flag`）；桌面端由 CSS 隐藏 |
| `build-tag` | 元素（当前为 `<span>`） | 构建标记 | 由 `Main` 写入当前构建号；用于确认没有加载缓存里的旧脚本 |
| `easter-egg-root` | 元素（当前为空 `<div>`） | 彩蛋挂载根节点 | 保持为空；不注册彩蛋 |

附加约束：

- `difficulty-select` 是三档按钮组，按钮的 `data-difficulty` 固定为 `easy` / `medium` / `hard`，必须与 `Config.DIFFICULTIES` 的 key 一致；不得增删按钮或改名。
- 初始难度由 `Config.DEFAULT_DIFFICULTY_KEY` 决定，不从按钮当前选中态推导。
- `game-canvas` 的 `width` / `height` 由 `Main` 按 `Config.BOARD.CANVAS_*` 写入，不得在 HTML 里写死。
- `mode-select` 的按钮 `data-mode` 固定为 `reveal` / `flag`。触屏（`pointer: coarse`）显示并用它切换操作模式；桌面端由 CSS 隐藏，保持「左键翻开、右键插旗」。
- HUD 由 Main 在初始化和每次操作回调后同步。
- CSS 类名与布局不属于冻结契约；可以调整视觉，但不得破坏上述 id 或改变其语义。

---

## 4. 全局命名空间（冻结）

唯一允许的全局入口：

```js
window.MinesweeperLives = {
  Config: Object,
  State: Object,
  Board: Object,
  Renderer: Object,
  Input: Object,
  EasterEggs: Object,
  Main: Object
};
```

规则：

- 所有模块使用 IIFE + `'use strict'`，内部变量不得泄漏到 `window`。
- 除 `window.MinesweeperLives` 外，不得新增任何全局变量、全局函数或全局类。
- 跨模块通信必须通过 `window.MinesweeperLives.*` 或显式函数参数完成。
- 已有命名空间属性、模块方法、文件名、DOM id、事件名、Config 字段、数据字段、函数签名均为冻结内容。
- 新增命名空间属性或方法前，必须先更新本文件；不得重命名或覆盖已有成员。
- `Config` 在运行时被深冻结（deep freeze），只读。其他模块 API 对象未做运行时冻结，但同样按契约视为只读。

---

## 5. Config 字段（冻结）

### 5.1 难度

`Config.DIFFICULTIES` 是以难度 key 为键的对象。每档必须包含 `key`、`label`、`mines`。

| 对象 key | `key` | `label` | `mines` |
| --- | --- | --- | --- |
| `easy` | `"easy"` | `"低（20 雷）"` | **20** |
| `medium` | `"medium"` | `"中（30 雷）"` | **30** |
| `hard` | `"hard"` | `"高（50 雷）"` | **50** |

- 雷数是已确认的产品值，不得改动。
- `Config.DIFFICULTY_ORDER` 固定为 `["easy", "medium", "hard"]`。
- 不得擅自增加第四档难度，或在 `mines` 中写入其它数值。

### 5.2 其余字段

| 字段 | 值 / 类型 | 说明 |
| --- | --- | --- |
| `Config.DEFAULT_DIFFICULTY_KEY` | `"medium"` | 初始难度：页面加载即按中难度开局，仍可用难度按钮切换 |
| `Config.INITIAL_LIVES` | `8` | **已确认：三档难度统一 8 条生命** |
| `Config.BOARD.ROWS` | `16` | 已确认：棋盘行数 |
| `Config.BOARD.COLS` | `16` | 已确认：棋盘列数 |
| `Config.BOARD.CANVAS_WIDTH` | `512` | 已确认：Canvas 逻辑宽度（px）= 16 × 32 |
| `Config.BOARD.CANVAS_HEIGHT` | `512` | 已确认：Canvas 逻辑高度（px）= 16 × 32 |
| `Config.BOARD.CELL_SIZE` | `32` | 已确认：单元格像素尺寸（px） |
| `Config.FIRST_REVEAL_SAFE` | `false` | 已确认的玩法约束：首次翻开不保证安全 |
| `Config.RANDOM_SOURCE` | `"Math.random()"` | 暂定随机来源；**- 待确认：是否需要可复现种子或加密随机** |
| `Config.STATUS` | 对象 | 状态枚举，见 5.3 |
| `Config.EVENTS` | 对象 | 彩蛋事件名，见第 8 节 |

`null` 是“未配置”的显式哨兵值，不是 0，也不得被渲染或输入换算当作有效数值。

### 5.3 状态枚举

`Config.STATUS`：

| 常量 | 字符串值 | 含义 |
| --- | --- | --- |
| `IDLE` | `"idle"` | 尚未开始 |
| `PLAYING` | `"playing"` | 对局进行中 |
| `WON` | `"won"` | 已胜利（胜负规则后续步骤实现） |
| `LOST` | `"lost"` | 已失败 / 死亡（生命规则后续步骤实现） |

`GameState.status` 只允许以上四个字符串，不得使用其它值。状态迁移规则不在第 1 步定义。

---

## 6. 数据结构契约

### 6.1 坐标与棋盘表示

- `row`、`col` 均为 **0-based 整数**。
- `GameState.cells` 是二维数组：`cells[row][col] = Cell`。
- 行数 / 列数未确认前，`cells` 保持 `[]`，不得编造行列或生成占位格子充当真实棋盘。

### 6.2 Cell

`Board.createCell(row, col)` 必须返回以下字段；字段名、含义不得改变：

| 字段 | 类型 | 初始值 | 含义 |
| --- | --- | --- | --- |
| `row` | `number` | 传入值 | 行下标（0-based） |
| `col` | `number` | 传入值 | 列下标（0-based） |
| `isMine` | `boolean` | `false` | 是否为地雷 |
| `adjacentMines` | `number` | `0` | 8 邻域地雷数；本步骤未实现计算 |
| `isRevealed` | `boolean` | `false` | 是否已翻开 |
| `isFlagged` | `boolean` | `false` | 是否已插旗 |
| `isExploded` | `boolean` | `false` | 是否作为爆炸地雷被标记；展示规则后续定义 |

不得删除或重命名上述字段。新增字段必须先更新本契约。

### 6.3 GameState

初始状态由 `State.createInitialState(difficultyKey)` 创建，必须包含：

| 字段 | 类型 | 初始值 | 含义 |
| --- | --- | --- | --- |
| `difficultyKey` | `string \| null` | `null` | 已选难度 key；缺省/非法时为 `null`，不自动回退 |
| `rows` | `number` | `Config.BOARD.ROWS`（16） | 棋盘行数 |
| `cols` | `number` | `Config.BOARD.COLS`（16） | 棋盘列数 |
| `mineCount` | `number \| null` | `null`；合法难度时为该档 `mines` | 本局地雷总数 |
| `cells` | `Cell[][]` | `[]` | `cells[row][col]`，维度确认前留空 |
| `lives` | `object` | 见 6.4 | 生命值容器 |
| `status` | `string` | `"idle"` | 只允许 `idle` / `playing` / `won` / `lost` |
| `firstRevealDone` | `boolean` | `false` | 是否已经发生首次翻开 |
| `firstRevealWasMine` | `boolean \| null` | `null` | 首次翻开是否踩雷；仅在 `firstRevealDone === true` 时有意义 |
| `flagsUsed` | `number` | `0` | 已使用旗子数；规则后续实现 |
| `revealedCount` | `number` | `0` | 已翻开格数；规则后续实现 |
| `startedAt` | `number \| null` | `null` | 开始时间，Unix epoch 毫秒 |
| `endedAt` | `number \| null` | `null` | 结束时间，Unix epoch 毫秒 |

`firstRevealWasMine` 初始为 `null` 是**刻意设计**：它不是“首点安全”的证明。任何实现都必须先检查 `firstRevealDone`，再读取该字段。

### 6.4 lives

`GameState.lives` 必须包含：

| 字段 | 类型 | 初始值 | 含义 |
| --- | --- | --- | --- |
| `current` | `number` | `Config.INITIAL_LIVES`（8） | 当前剩余生命 |
| `initial` | `number` | `Config.INITIAL_LIVES`（8） | 初始生命上限 |
| `lostHistory` | `array` | `[]` | 生命流失记录 |

`lostHistory` 的元素至少包含：

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `reason` | `string \| null` | 失去生命的原因；**- 待确认：原因取值集合** |
| `at` | `number \| null` | 发生时间，Unix epoch 毫秒 |
| `row` | `number \| null` | 关联行；与具体格子无关时为 `null` |
| `col` | `number \| null` | 关联列；与具体格子无关时为 `null` |

第 1 步不会产生任何 `lostHistory` 记录，也不实现生命扣除。

### 6.5 初始状态示例

以 `medium` 为例，`State.createInitialState('medium')` 只装配占位状态（`cells` 仍为 `[]`，真实棋盘由 `startGame` 生成）：

```json
{
  "difficultyKey": "medium",
  "rows": 16,
  "cols": 16,
  "mineCount": 30,
  "cells": [],
  "lives": {
    "current": 8,
    "initial": 8,
    "lostHistory": []
  },
  "status": "idle",
  "firstRevealDone": false,
  "firstRevealWasMine": null,
  "flagsUsed": 0,
  "revealedCount": 0,
  "startedAt": null,
  "endedAt": null
}
```

若未提供合法难度，则 `difficultyKey` 与 `mineCount` 均为 `null`。

### 6.6 初始状态装配规则

`State.createInitialState(difficultyKey)` 必须遵守：

1. 仅当 `difficultyKey` 是 `easy` / `medium` / `hard` 之一时，写入对应 `difficultyKey` 和 `mineCount`。
2. 缺省、空值或非法 key 时，二者均为 `null`；**不自动回退到任何难度**。
3. `rows` / `cols` 直接使用 `Config.BOARD.ROWS` / `COLS`，当前为 16 / 16。
4. `cells` 在 `createInitialState` 中保持 `[]`；真实棋盘只由 `startGame` 调用 `Board.generateRandomBoard` 生成。
5. `lives.current` / `lives.initial` 使用 `Config.INITIAL_LIVES`，当前为 8。
6. `status` 为 `"idle"`，`firstRevealDone` 为 `false`，`firstRevealWasMine` 为 `null`。
7. 不随机布雷，不创建棋盘，不派发事件，不启动计时。

---

## 7. 首次翻开策略（冻结，非待确认）

这是产品已确认规则，后续步骤必须遵守：

1. **第一次打开不保证为 0，也不保证安全；首次点击可能直接踩到炸弹。**
2. `firstRevealDone` 与 `firstRevealWasMine` 字段必须保留。
3. `firstRevealWasMine` 初始为 `null`；只有首次翻开真正发生后，才允许写入 `true`/`false`。
4. `Board.generateRandomBoard` 最终实现必须随机布雷；**不得默认保证首次点击安全**。
5. `generateRandomBoard` 的 `options.firstRevealSafe` 默认值必须为 `false`。
6. 不得在首次点击后搬移地雷、重新布雷、强制把首点改成 0 格或扩大空白区域，以制造“首点安全”。
7. 本步骤没有实现首次点击流程，也没有任何首点保护逻辑。
8. 若未来需要改变此规则，必须先由用户明确确认并更新本契约；任何模块不得静默加入首点安全逻辑。

---

## 8. 彩蛋事件（冻结）

`Config.EVENTS` 的事件常量、字符串值、钩子方法名固定如下：

| 常量 | 字符串值 | 钩子方法 | 设计用途 |
| --- | --- | --- | --- |
| `GAME_INIT` | `"game:init"` | `onGameInit` | 游戏初始化后 |
| `BEFORE_REVEAL` | `"cell:before-reveal"` | `onBeforeReveal` | 翻开某格之前 |
| `AFTER_REVEAL` | `"cell:after-reveal"` | `onAfterReveal` | 翻开某格之后 |
| `LIFE_LOST` | `"life:lost"` | `onLifeLost` | 生命流失后 |
| `GAME_END` | `"game:end"` | `onGameEnd` | 对局结束 |
| `RENDER` | `"render"` | `onRender` | 完成一次渲染后 |

规则：

- 事件字符串值是冻结契约，不得改名或新增同义事件。
- 每个事件只对应上述一个钩子名，映射不得改变。
- 第 1 步**不自动派发任何事件**；`EasterEggs.emit` 机制可直接使用。
- 事件 payload 结构与钩子返回值语义（例如是否允许取消翻开）**- 待确认**，后续步骤需要先补齐契约再依赖。
- 钩子调用签名固定为 `hook(payload, context)`。

---

## 9. 模块接口契约

以下函数签名冻结。当前实现只允许是骨架、占位或空实现。

### 9.1 State

```js
MinesweeperLives.State.createInitialState(difficultyKey)
// => GameState

MinesweeperLives.State.getState()
// => GameState | null

MinesweeperLives.State.setState(nextState)
// => GameState | null

MinesweeperLives.State.patchState(partial)
// => GameState | null

MinesweeperLives.State.resetState(difficultyKey)
// => GameState
```

| 方法 | 契约 |
| --- | --- |
| `createInitialState` | 按第 6 节创建并返回占位 GameState，不生成棋盘、不布雷 |
| `getState` | 返回当前状态引用；Main.init 之前为 `null`。调用方只应读取 |
| `setState` | 整体替换当前状态，返回替换后引用；当前不做结构校验 |
| `patchState` | 浅合并到当前状态，返回合并后引用；嵌套对象必须整体传入；无当前状态时返回 `null` |
| `resetState` | 等价于 `setState(createInitialState(difficultyKey))`，返回新状态 |

本步骤额外约束：

- 不派发任何彩蛋事件。
- 不实现状态结构校验、生命规则、胜负规则或计时启动。
- 当前状态只保存在内存中，不持久化。

### 9.2 Board

```js
MinesweeperLives.Board.createCell(row, col)
// => Cell

MinesweeperLives.Board.createBoard(rows, cols)
// => Cell[][]

MinesweeperLives.Board.generateRandomBoard(rows, cols, mineCount, options)
// => Cell[][]

MinesweeperLives.Board.countAdjacentMines(board, row, col)
// => number

MinesweeperLives.Board.getCell(state, row, col)
// => Cell | null
```

| 方法 | 契约 |
| --- | --- |
| `createCell` | 返回第 6.2 节完整 Cell 对象；不做坐标范围校验 |
| `createBoard` | 返回 `board[row][col]` 二维数组；参数不是正整数时返回 `[]` |
| `generateRandomBoard` | **最终契约**：随机布雷、雷数等于 `mineCount`、`options.firstRevealSafe` 默认 `false`、首点可能踩雷。**当前**：仅返回全非雷占位棋盘，不随机、不写雷 |
| `countAdjacentMines` | 统计 8 邻域地雷数；**当前**：空实现，固定返回 `0` |
| `getCell` | 从 `state.cells[row][col]` 返回 Cell；越界或状态缺失返回 `null` |

`generateRandomBoard` 的 `options` 契约：

- 缺省等价于 `{ firstRevealSafe: false }`。
- `firstRevealSafe` 默认 `false`，本产品当前不允许通过它制造首点安全。
- 其它 options 字段暂未定义；新增字段需先更新契约。
- 本步骤没有调用 `Math.random()`，也没有地雷位置生成逻辑。

### 9.3 Renderer

```js
MinesweeperLives.Renderer.init(canvasElement, state)
// => void

MinesweeperLives.Renderer.render(state)
// => void

MinesweeperLives.Renderer.destroy()
// => void
```

| 方法 | 契约 |
| --- | --- |
| `init` | 获取 Canvas 2D 上下文并保存引用；canvas 非法或 2D 不可用时抛错；不写 `width` / `height` |
| `render` | 一次性静态占位绘制；不改写 state、不启动循环、不更新 HUD |
| `destroy` | 清空画布并释放引用；不删除 DOM；当前无需清理监听器/动画帧 |

本步骤额外约束：

- 无 `requestAnimationFrame`、`setTimeout` / `setInterval`、动画、CSS transition。
- 不绘制真实棋盘，只绘制静态占位文字与边框。
- 不派发 `RENDER` 事件；事件接入点后续确认。
- 占位绘制使用 Canvas 当前实际尺寸；最终逻辑尺寸保持待确认。

### 9.4 Input

```js
MinesweeperLives.Input.bind(rootElement, callbacks)
// => void

MinesweeperLives.Input.unbind()
// => void
```

`callbacks` 至少包含：

| 回调 | 签名 | 语义 |
| --- | --- | --- |
| `onCellClick` | `(row, col) => void` | 左键点击某个格子（0-based 坐标） |
| `onCellContextMenu` | `(row, col) => void` | 右键点击某个格子 |
| `onDifficultyChange` | `(difficultyKey) => void` | 难度选择变化，值为 `easy` / `medium` / `hard` |
| `onRestart` | `() => void` | 点击重新开始 |

本步骤行为：

- `bind` 仅校验参数并保存 `rootElement` / `callbacks`；**不注册任何 DOM 监听器**，四个回调都不会被调用。
- `unbind` 仅清除保存的引用。
- 不做坐标换算、不修改 state、不执行游戏规则。
- Main 当前传入 `document` 作为 `rootElement`。

后续实现约束：

- 坐标必须换算为 0-based `row` / `col`，依赖 `Config.BOARD.CELL_SIZE` 与棋盘尺寸。
- Input 只负责把用户操作交给回调；翻开、插旗、扣命、重置等规则不得写进 Input。
- 右键菜单只应在游戏画布上阻止默认行为，不得影响页面其它区域。

### 9.5 EasterEggs

```js
MinesweeperLives.EasterEggs.init(context)
// => void

MinesweeperLives.EasterEggs.registerEasterEgg(id, hooks)
// => boolean

MinesweeperLives.EasterEggs.emit(eventName, payload)
// => number

MinesweeperLives.EasterEggs.listEasterEggs()
// => string[]
```

| 方法 | 契约 |
| --- | --- |
| `init` | 保存 context；可重复调用，只更新 context，不清空已注册彩蛋 |
| `registerEasterEgg` | 注册唯一彩蛋 id；`id` 会 trim；`hooks` 至少包含一个受支持钩子；成功返回 `true`；非法或重复返回 `false` |
| `emit` | 按注册顺序调用匹配钩子；未知事件告警并返回 `0`；返回实际调用的钩子数（即使钩子抛错也计入） |
| `listEasterEggs` | 返回按注册顺序排列的 id 数组副本 |

`init(context)` 由 Main 传入的形状：

```js
{
  config,          // Config（只读）
  getState,        // State.getState
  canvasElement,   // #game-canvas
  rootElement      // #easter-egg-root
}
```

钩子形状：

```js
{
  onGameInit(payload, context) {},
  onBeforeReveal(payload, context) {},
  onAfterReveal(payload, context) {},
  onLifeLost(payload, context) {},
  onGameEnd(payload, context) {},
  onRender(payload, context) {}
}
```

本步骤额外约束：

- 不注册任何具体彩蛋；`listEasterEggs()` 当前返回 `[]`。
- 单个钩子抛错会被捕获并 `console.error`，不阻断其它钩子。
- 不支持运行时注销；重复 id 不会覆盖。
- 第 1 步不自动 emit 任何事件。
- 彩蛋具体内容、DOM 呈现方式与 payload 结构不在本步骤实现。

### 9.6 Main

```js
MinesweeperLives.Main.init()
// => void
```

契约：

- 幂等；重复调用直接返回。
- 因脚本位于 `body` 末尾，`main.js` 在文件末尾自动调用一次 `Main.init()`。
- 读取并校验全部六个固定 DOM id；缺失任一节点则抛出错误。
- 用 `Config.DEFAULT_DIFFICULTY_KEY` 创建初始占位 GameState，并通过 `State.setState` 写入当前状态；不从 `difficulty-select` 推导默认难度。
- 初始化 EasterEggs context、Renderer，并调用 `Input.bind(document, callbacks)`。
- 调用一次 `Renderer.render(State.getState())`。
- 回调目前全部是 TODO 占位，不实现翻开/插旗/难度切换/重开规则。
- 不实现游戏规则、不更新 HUD、不启动渲染循环、不派发彩蛋事件。

---

## 10. 依赖清单（冻结）

允许使用：

- HTML5
- CSS
- 原生 JavaScript（现代浏览器支持的语法）
- Canvas 2D API
- DOM API

禁止使用：

- npm、`package.json`、任何打包器/构建工具/开发服务器；
- 框架（React / Vue / Svelte 等）；
- 任何第三方库、工具函数库、外部字体、CDN、网络资源；
- 动态 `import()`、异步脚本加载、运行时模块加载、构建时注入；
- WebGL、Web Worker、Service Worker、网络请求；
- 本步骤中的动画库或逐帧渲染。

其它：

- `assets/` 为空，不包含图片、字体或音频。
- 随机数来源暂定为 `Math.random()`；**- 待确认：是否需要可复现种子或加密安全随机**。
- 不依赖后端，不持久化数据，不使用 localStorage / IndexedDB。
- 可直接通过 `file://` 打开；页面不发起网络请求。

---

## 11. “不要动态”的边界

**- 待确认：不要动态的具体边界。**

当前采用最保守的静态骨架解释并已按此实现：

- 不使用构建工具、框架、路由、动态 import、异步加载或运行时模块加载；
- 不使用 `requestAnimationFrame`、定时器、Canvas 重绘循环或动画；
- CSS 不使用 animation / transition；
- 仅在 `Main.init()` 时执行一次静态 Canvas 占位绘制。

仍需确认：用户所说的“不要动态”是指只禁止构建/加载层面的动态，还是也禁止后续的逐帧动画、Canvas 动态刷新或任何交互反馈动态。该边界确认前，第 2～6 步不得擅自引入渲染循环或动画。

---

## 12. 待确认项（完整清单）

| # | 项目 | 状态 | 说明 |
| --- | --- | --- | --- |
| 1 | **初始难度** | ✅ 已确认 | `Config.DEFAULT_DIFFICULTY_KEY = "medium"`，页面加载即按中难度开局；仍可用难度按钮切换 |
| 2 | **默认生命值数量** | ✅ 已确认 | 三档难度统一 `Config.INITIAL_LIVES = 8` |
| 3 | **棋盘行数 / 列数** | ✅ 已确认 | 16 × 16，三档共用同一棋盘尺寸 |
| 4 | **Canvas 尺寸** | ✅ 已确认 | 512 × 512 逻辑像素，由 `Main.init` 写入 `width` / `height` |
| 5 | **单元格像素尺寸** | ✅ 已确认 | 32 px，点击坐标换算已按该值实现 |
| 6 | **“不要动态”的具体边界** | - 待确认 | 当前无动画、无 rAF、无定时器；仅在初始化与每次操作回调后一次性重绘 |
| 7 | **随机数来源** | - 待确认 | 暂用 `Math.random()`，已实际用于布雷 |
| 8 | **HUD 更新职责与时序** | ✅ 已实现 | 由 Main 在初始化与操作回调后同步 `#lives-value` / `#status-value` |
| 9 | **生命流失 reason 取值** | - 待确认 | 当前唯一取值 `"mine"`，集中在 `state.js` 常量中 |
| 10 | **彩蛋 payload 结构与钩子返回值语义** | - 待确认 | 事件名已冻结；payload 未定义 |
| 11 | **Canvas 高 DPI / 缩放策略** | - 待确认 | 未处理 `devicePixelRatio`；当前按逻辑尺寸绘制 |

> **已确认**：三档雷数 20 / 30 / 50；统一 8 条生命；棋盘 16 × 16、单元格 32px、Canvas 512 × 512；状态枚举四个值；首次翻开**不保证安全**，可能是炸弹。

---

## 13. 实现状态清单（v2）

| 主题 | 状态 |
| --- | --- |
| 目录、入口、固定加载顺序 | ✅ 已完成 |
| 六个稳定 DOM id | ✅ 已完成 |
| 全局命名空间 `window.MinesweeperLives` | ✅ 已完成 |
| 三档难度 20 / 30 / 50 | ✅ 已确认并写入 Config |
| 统一 8 条生命 | ✅ 已确认并写入 Config |
| 棋盘 16 × 16 / 单元格 32px / Canvas 512 × 512 | ✅ 已确认并写入 Config |
| Cell / GameState / lives 结构 | ✅ 已定义 |
| State 五个接口 | ✅ 签名完整；已实现开局 / 翻格 / 插旗 / 扣命 / 胜负 |
| Board 五个接口 | ✅ 签名完整；已实现随机布雷 / 邻雷 / 零格扩散 |
| Renderer 三个接口 | ✅ 签名完整；按真实棋盘一次性绘制 |
| Input 两个接口 + 四个回调 | ✅ 签名完整；已接入左键翻格与右键插旗 |
| EasterEggs 四个接口 + 六个钩子 | ✅ 机制完整；无具体彩蛋 |
| 首次翻开不保证安全 | ✅ 已冻结；无任何安全保护实现 |
| 随机布雷 / 翻开 / 插旗 / 扣命 / 胜负 | ✅ 已实现 |
| 输入交互 | ✅ 已实现（桌面左右键 / 触屏模式切换） |
| 剩余安全格 HUD | ✅ 已实现 |
| 触屏「选择 / 插旗」模式 | ✅ 已实现 |
| 渲染循环 / 动画 | ❌ 未实现（“不要动态”边界待确认） |
| 具体彩蛋内容 | ❌ 未实现（后续步骤） |

---

## 14. 变更记录

| 版本 | 日期 | 变更 |
| --- | --- | --- |
| v1 | 2026-11-21 | 第 1 / 6 步静态 Canvas 骨架：创建目录、入口、Config、数据结构、模块签名、彩蛋入口与依赖契约 |
| v2 | 2026-11-21 | 确认并写入：棋盘 16 × 16、单元格 32px、Canvas 512 × 512、统一 8 条生命、初始难度 `medium`；同步 §5.2 / §6 / §12 / §13 |
| v3 | 2026-11-21 | 新增 `#remaining-value`（剩余安全格）与 `#mode-select`（触屏「选择 / 插旗」模式）；桌面左右键行为不变；补充 §3 / §13 |
| v4 | 2026-11-21 | 新增 `#build-tag` 构建标记与 `?v=` 缓存串，避免浏览器继续执行缓存里的旧脚本；补充 §2 / §3 |
