# 模拟器的契约：还原 WE 的 API 面，不自检，替身显式化

## 背景

本地调试壁纸需要在没有 Wallpaper Engine 的情况下跑起来，因此有一个"WE 模拟器"。旧实现（`tools/wallpaper-engine-simulator.js`，1589 行）在这个位置上出过**事故级**的错：它靠 `typeof window.wallpaperRegisterListener === "function"` 来判断"我是不是已经在真实 WE 里"，而这个 API **在真实 WE 里不存在**——判据恒为 false，于是模拟器在真实 WE 里也会自我激活并覆盖官方 API。

WE 实际注入的网页壁纸 API 只有 `window.wallpaperPropertyListener`（外加属性/通用属性/暂停/用户目录文件变更这几个回调）。`window.wallpaperRegisterListener` 与 `window.wallpaperEngine` 都不存在。

## 决策

### 1. 不做环境自检；由注入决定它是否存在

模拟器**没有**任何"我在哪"的判断。它只在有人把一个 `<script>` 注入页面时才存在——注入是事实，不是猜测，不存在误判空间。旧实现反过来做（靠 `typeof window.wallpaperRegisterListener === "function"` 自检），而那个 API 在真实 WE 里不存在，判据恒为 false，于是它在真实 WE 里也自我激活并覆盖官方 API。事故级。

**注入点有两个，都合法，但用途不同：**

| 场景 | 谁注入 | 模拟器本体从哪来 | 产物 |
| --- | --- | --- | --- |
| `pnpm dev` | 调试服按路由注入 | 调试服自己的 `/simulator/wallpaper-engine.js` | 分发目录**保持干净** |
| 静态托管（GitHub Pages） | 构建期写进 `index.html` | 分发自带的 `./scripts/wallpaper-engine.js` | `pnpm build --with-sim` |
| 上传 Wallpaper Engine | 没有人注入 | 不存在 | `pnpm build`（默认） |

默认的发布产物里**没有**模拟器文件，也**没有**任何注入痕迹——它必须与"用户从创意工坊下载到的东西"完全一致。

#### 两条供给路径各自踩过的坑

**调试服路径**：驱动原先把动态 `import()` 指向 `/release/<dir>/scripts/wallpaper-engine.js`，而那个文件只有 `--with-sim` 才会被复制进分发——于是默认构建下 `pnpm dev` 必然 404、**面板静默消失**。404 只留在控制台里，看起来像"面板没渲染"，很难联想到是构建产物缺了文件。现在调试服从自己的路由提供，与分发目录里有没有它无关。

**静态托管路径**：地址必须是**相对**的 `./scripts/wallpaper-engine.js`。GitHub Pages 把站点放在 `/<repo>/` 子路径下，根绝对路径 `/scripts/…` 会 404。这一点由 `tools/checks/verify-static-preview.mts` 把关——它刻意把分发挂在 `/repo/` 前缀后面服务，挂在根上测不出这个错。

两条路径会在 `--with-sim` 构建 + 调试服同时出现时重叠，所以驱动带幂等闸（`window.__weSimDriver`）。没有它模拟器会被 mount 两遍，页面上出现两个面板。

#### 为什么不让 `pnpm dev` 自动带上 `--with-sim`

那样能一行修好调试路径，但代价是调试时看到的分发目录多了一个文件，不再是你要上传的那份。"调试对象 == 发布对象"这条不变量比少写一行更重要。

### 2. 公开面严格等于 WE 的公开面

模拟器只提供 WE 真正有的东西，一个不多：

- `window.wallpaperPropertyListener`（**等壁纸自己注册**，绝不代注册）；
- 不提供 `window.wallpaperEngine`、`window.wallpaperRegisterListener`、`wallpaperGetUserDataPath` 等 WE 没有的全局。

理由：一个凭空承诺的 API 比没有 API 更危险——壁纸会依赖它，然后在真实环境里崩。冒烟测试里有两项断言就是专门盯这个：`typeof window.wallpaperEngine === "undefined"`。

### 3. 属性下发语义

- 初始属性**一次整批**交给 `applyUserProperties`，不逐条发（逐条会让壁纸的 `render()` 被调用 N 次，掩盖真实的性能与竞态）。
- 顺序：先 `applyGeneralProperties`（fps），再 `applyUserProperties`。
- **下发前必须等到 listener 就位**。`?__propsAt=dom` 复现的正是"属性早于壁纸模块到达"这条竞态；此时 listener 还是 undefined，直接下发会被静默吞掉、页面停在默认预设上。真实 WE 不会丢（属性在消息队列里），所以模拟器等，且**只等不代注册**——代注册会掩盖"壁纸忘了在模块顶层注册 listener"这个真错误。
- 壁纸必须在模块顶层注册 listener（见 `src/runtime/index.ts`），否则属性在 `load` 之前到达时收不到。

### 4. 替身必须显式化

浏览器不是 CEF，有几件事物理上做不到。它们不被伪装成"和 WE 一样"，而是列入 `window.__weSim.substituted`，并在面板顶部有一条**常驻**的「⚠ 模拟环境」横幅：

| 能力 | WE 的行为 | 模拟器的替身 |
| --- | --- | --- |
| `file` / `texture` / `directory` 选择器 | 弹原生对话框，回传 `file:///` 绝对路径 | `<input type=file>` + `URL.createObjectURL`（回传 `blob:`） |
| 用户数据目录绝对路径 | `wallpaperGetUserDataPath` 返回真实路径 | 虚拟路径 |
| `document.cookie` | CEF 里被隔离 | 浏览器里可用（未隔离） |

### 5. 装载时序

模拟器源码是 ES module（要能正常用 `import`/`export` 写类型），但**不能用 `<script type="module">` 装载**：module 脚本会被延迟到解析完成后执行，那样它就不可能早于壁纸模块就位。驱动脚本因此是一个**经典** `<script>`，内部用动态 `import()` 装载模拟器。两者都由 `tools/lib/drivers.ts` 生成，调试服与对拍测试台共用同一份。

## 未采纳的方案

- **靠某个全局变量的存在自检**：这正是旧实现的事故成因，见第 1 条。
- **提供 `wallpaperEngine` 之类的便利全局**：见第 2 条。
- **替模拟器实现真实文件路径**：浏览器做不到，伪装只会让壁纸在真机上表现不同。
- **用 `<script type="module">` 直接加载模拟器**：时序不成立，见第 5 条。