# 自包含模拟包：把 `file://` 下的不可能变成可能

## 背景

`pnpm dev` 起本地服务、在浏览器里调壁纸，这条路径很好用，但它有一个硬前提：**有一个 HTTP 服务在跑**。要给别人看一眼效果、要在没装依赖的机器上确认"这档壁纸到底长什么样"、要把某一版效果截图存档，都得先把服务起起来。于是有了"自包含包"这个需求：一个 `sim/index.html`，双击就能开，不依赖 `pnpm dev`、不依赖任何服务器、也不依赖网络。

一开始以为这只是"把资源内联进 HTML"。实际做下来，`file://` 这个环境把四件平时根本不会注意到的事变成了拦路虎，每一件都值得记下来。

## 决策

### 1. 产物位置：`<分发根>/sim/index.html`，不往 `sim/` 里复制任何资源

自包含包是**分发目录的一部分**，不是一份独立产物：

```
dist/releases/single-hsr-kv37/
  index.html          ← 发布用（ES module，需要 http）
  project.json
  preset.js
  images/ effects/ audios/        ← 布局见 ADR 0008：现在是 spines/<骨架名>/ scene/ audios/
  sim/index.html      ← 自包含（经典脚本 + 全内联，双击可开）
```

好处是它天然跟着分发走：拷走整个分发目录，发布用的那份和调试用的那份一起走。代价是页面不在分发根下，所以**资源根**和**模块根**要分开算——这是本 ADR 第 4 条，也是这次最费时间的一个坑。

资源一律不复制进 `sim/`。复制会让"分发目录里多出一份重复的 2 MB 贴图"，且一旦漏拷一个就是白屏；全部内联则"要么整页可用，要么构建期就报错"，没有中间状态。

### 2. 一切内联：模块、资源、音频都变成页面里的字节

`file://` 下浏览器把页面当成 `origin: null`，于是：

| 做法 | `file://` 下 | 结论 |
| --- | --- | --- |
| `<script type="module">` | 拒绝（CORS） | 不能用 |
| `import()` / `fetch()` / `XHR` | 拒绝（CORS） | 不能用 |
| 同目录相对 `<img>` / `<audio>` | 可以 | 可用但不必要 |
| 跨目录 file 资源 | 拒绝 | 不能用 |
| `data:` URL | 处处可用 | **选它** |
| 内联 `<script>` | 可用 | **选它** |

所以自包含包 = 一份 HTML，里面依次是：spine-player（内联）→ 属性下发 → 模块注册表 → 模拟器模块 → 驱动脚本 → 壁纸运行时。所有 ES module 被合成**经典脚本**，用一张 `__weModules` 注册表 + `__require(id)` 还原 `import` 语义；所有资源（图片/骨架 JSON/atlas/贴图页/音频）转成 `data:` URL，装在一张以 URL 为键的表里。

`import` 改写是**保声明**的：`export const X = 1` 会变成 `const X = 1` 加末尾一行 `exports.X = X`。早期版本直接改成 `exports.X = 1`，把模块内的局部绑定删掉了——`REFERENCE_ASPECT is not defined`，而且只在第一帧渲染时才炸（默认参数到那时才求值），构建、加载、尺寸检查全部正常。

### 3. 音频内联是可选项（`--no-embed-audio`）

`xilian-src.flac` 是 37.7 MB，base64 后 50.3 MB。默认内联（这样双击就有声音），但提供开关给"只看画面、不在乎体积"的场合。关闭时构建会明确列出哪些音频没内联、以及后果（"双击打开时选不到它们"），而不是安静地少一块功能。

### 4. 两个根必须分开算（**本次最大的坑**）

页面的位置和模块的位置**不是同一个基准**：

- **页面根**：自包含页永远在 `<分发根>/sim/index.html`，资源相对**分发根**寻址，所以相对页面是 `"../"`——**与合集深度无关**。
- **模块根**：`preset.js` 在 `<分发根>/<壁纸id>/preset.js`（合集）或 `<分发根>/preset.js`（单档），发布版用 `new URL("./", import.meta.url)` 相对**自己所在目录**推导，所以相对页面是 `"../<壁纸id>/"`。

这两个值曾经都被写成"页面根 × 分发深度"，于是：

- `collection-all`（深度 2）的资源根变成 `"../../"`，跑到 `dist/releases/` 去了；
- 合集分发的 `preset.js` 把 `./audios/kv37/x.mp3` 解析到 `<releases>/audios/...`（少一层），音频退回 `file://` 读，报 `ERR_FILE_NOT_FOUND`。

两个错误的现象都长成"表和模块看起来都对，只有某个资源不对"，非常容易误判成那个资源自己的内联逻辑有问题。**单档分发两种错误都不会出现**（深度 0、没有 `<壁纸id>/` 这一段），所以只测单档会一路绿灯。

对应地，资源表的建键基准是**分发根**（`assetRelIn`，合集里带 `<壁纸id>/`），而不是 `preset.js` 的相对路径（`assetUrlIn`）。用后者建键会丢掉 `<壁纸id>/` 这一段。

### 5. 表要同时按"相对键"和"绝对键"注册

运行时拿到的 URL 有两种形态：`preset.js` 求值出来的**绝对** URL（`file:///…/images/kv37.webp`），和 spine-player 内部按 `pathPrefix + 相对路径` 拼出来的**相对**串。两者都要能查中，所以每份资源都注册 `key`、`./key`、`/key`、裸名，以及每个键 `new URL(k, base).href` 的绝对形式。

spine-player 的 `rawDataURIs` 尤其要注意：`loadTexture(path)` 用 `path` 查表、但把回调注册在**原来的** `path` 上，而 `loadTextureAtlas` 传下来的 `path` 是 `atlasUrl 的父目录 + 页名`。因此 `config.rawDataURIs` 要合并 `byRelative` 与 `byAbsolute` **两族**键，且 `jsonUrl`/`atlasUrl`/`binaryUrl` 三个值也要各自以绝对键登记。少了任何一族，spine 就安静地退回 XHR，在 `file://` 下被 CORS 拦掉。

这些键一旦对不上，症状是白屏加一条 `net::ERR_FILE_NOT_FOUND`，**看不出是哪个键**。所以 `WrappedSpinePlayer` 里有一道**生产断言**：三个键任何一个不在合并后的表里就立刻抛错，并打印缺的那个键名。先前的三轮错误猜测都是因为探针只打印了"表有多少个键"，而不是"运行时到底查了哪个键"。

### 6. 门禁：`check:dist` 检查自包含页的外部依赖

`check:dist` 对每个 `sim/index.html` 做三项断言：没有 `<script type="module">`、标签上没有 `http(s)://`/`file:///`/根绝对路径。

扫描前必须**剥掉内联脚本的内容**——spine-player 是整份内联的，它内部带着一段编辑器示例模板，里面有 `<script src="https://…">` 这样的字符串，直接对整页扫标签会把它们当依赖，四个分发全报假阳性。

剥除时**只删标签之间的内容，保留开标签本身**。第一版整体替换掉了开标签，于是所有 `<script src=…>` 都不再被检查，门禁看着在跑、实际只能查到 `<link>`。是"往页面里注入一个外链看它拦不拦得住"这个测试把这个漏洞暴露出来的——**一个从不失败的检查等于没有检查**，所以 `tools/checks/test-sim-gate.mts` 会注入四种外部依赖（外链 script、`file:///`、根绝对路径、`type=module`）确认每种都被拦下。

## 未采纳的方案

- **用 Service Worker 拦截 `file://` 请求**：`file://` 下不能注册 Service Worker。
- **让用户起一个 `file://` 代理或用 `--allow-file-access-from-files`**：那就又回到"需要额外操作"了，自包含的意义没了。
- **把资源复制进 `sim/` 而不内联**：跨目录 `file://` 资源读不到，同目录的也要靠相对路径，且会把分发体积翻倍。
- **只支持单档壁纸的自包含包**：合集分发的调试需求同样真实（要试预设切换、共享音频），而且正是它暴露了第 4 条那两个基准错误。
- **在页面上做环境自检来决定走哪条路**：与 ADR 0006 第 1 条同因——判据会恒为假。自包含与否由**构建产物形态**决定，不由运行时探测决定。

## 影响

- `pnpm build sim` 产出自包含包；`pnpm build sim <壁纸id>` / `sim collect` 收窄范围。
- 构建时间从 0.8 s 增至约 5 s（base64 编码 + 语法自检）；单页 15 MB（kv37）到 129 MB（内联 flac 的合集）。
- 验收靠 `tools/checks/verify-sim-page.mts`：用 CDP 以 `file://` 打开，断言画布有实际像素、0 异常、0 控制台报错、无 `http(s)` 请求。**像素采样必须在 `requestAnimationFrame` 内跨帧取最大值**——`preserveDrawingBuffer: false` 下在 rAF 外读 `gl.readPixels` 永远读到清空后的缓冲，会得到"0% 非透明"的假阴性。