feat: 比例适配、bgm 音源选择与 fps 限流，打包 v3

取景（issue 04） - 新增 viewport-fitter.js：让立绘层缩放跟随背景图的 cover 缩放——背景放大多少倍、特效就放大多少倍。原先背景走 cover、立绘层走 contain，比例一变两者就分叉。 16:9 下与作者设定逐像素一致（kv37 为 0 差异）。实测证伪了"contain 会裁掉作者视口" 这个最初的判断：contain 在任何比例下都完整含住作者视口。 - 应用方式为原地改写 config.viewport 字段后调 setViewport()，不重建播放器；维护挂在 config.frame 上按画布比例增量进行（config.success 早于 setViewport，拿不到视口）。 WE 属性（issue 05） - project.json 新增 bgm combo（所有壁纸音源的并集 + 「随预设」）；所选项不属于当前壁纸时音频回落该壁纸默认，选择本身保留。 - fps 限流包裹实例 drawFrame 并接管排程。修掉两个实测缺陷：朴素丢帧会把 rAF 抖动放大成整拍丢失（目标 30fps 实测只有 22.5fps）；fps:0 被真值判断吞掉导致无法取消限流。打包（issue 06） - project.json version 升至 3 并更新描述；preset 的 combo 取值保持 xilian/kv37 不变。 - preview.gif 821 KB → 347 KB（每 2 帧取 1 帧 + 128 色不抖动，逐帧与源帧像素完全相同）。 - index.html 加内联 favicon，消除 CEF 自动请求 /favicon.ico 造成的 404 报错。其它 - dist/scripts/wallpaper-engine.js 移到 tools/：它没有任何入口引用，且环境判据依赖真实 WE 并不存在的 wallpaperRegisterListener，一旦按它自己的说明挂进 index.html 会在生产环境自我激活。 - 修正死文件检查：原检查会拿文件名匹配到文件自身的内容，使这类文件漏网。 - 新增离线算式验证与 resize / 属性 / 全量验收三套浏览器测试脚本。
2026-09-19 20:29:25 +08:00
1 parent 4662856963
commit eb56efbd9e
@@ -1,20 +1,68 @@
 # 04 比例适配：按容器比例重算视口

-Status: ready-for-agent
+Status: resolved

 ## 问题

-viewport 以等比 "contain" 映射到画布：单轴贴边、另一轴多露出世界，因此现在的负 padding 只在目标比例下成立；
-在超宽屏（3440×1440）或竖屏（1080×1920）下会露出多余的世界或裁掉主体。
+viewport 以等比 "contain" 映射到画布：单轴贴边、另一轴多露出世界。
+原本的判断是"负 padding 只在目标比例下成立，其它比例会裁掉主体"——**实测证明这个判断是错的**，
+真正的病根是另一件事。

-## 步骤
+## 诊断（实测，非推测）

-1. 测出每档壁纸在 21:9 / 16:9 / 9:16 下的构图偏差（已有对拍矩阵）。
-2. 按容器宽高比在运行时重算 pad（视口是活对象：原地改 pad 后调用 `player.setViewport(当前动画名)` 即生效，
-   整体替换 viewport 会丢 `viewport.animations` 并在 spine-player 第 14973 行崩溃）。
-3. 目标：主体完整、底部对齐、无空边。
+先量清楚事实，再改代码：
+
+1. **contain 永远不会裁掉作者视口**。可见矩形是宽高比等于画布、且恰好含住作者视口 R 的最小矩形，
+   所以 R 在**任何**比例下都完整可见。比例不同只是"另一轴多露出世界"：
+   - 21:9 → 6453×2701（竖轴贴边、横轴多露）
+   - 16:9 → 6050×3403
+   - 9:16 → 1914×3403（横轴贴边）
+   三种比例下 `coversView` 全为 true，"裁掉作者视口"这条假设不成立。
+2. **这不是我重构引入的回归**。基线 `d8c7e49` 的 `preset-store.js` 里 xilian 的四个 pad
+   （-25% / -28% / -30% / -23%）与 kv37 的 `x: -1215, y: -410, w: 2048, h: 1024` 与现在一字不差；
+   基线的容器也是 `#spine-container` 绝对定位铺满、body flex 居中。取景语义未变。
+3. **真正的病根：背景走 cover，立绘层走 contain，两者缩放分叉。**
+   `body { background-size: cover }` 会按需放大裁切，立绘层却按 contain 固定世界矩形。
+   以 1080×1920 竖屏为例，背景被放大约 1.78 倍，立绘层的世界高度却纹丝不动——
+   特效于是和背景插画脱节，"多余世界"其实看不太出来，脱节才看得出来。
+4. **spine 资源路径是 `./effects/*.json`：立绘层是特效层，背景插画才是主体。**
+   所以判定标准不该是"特效不被裁切"（粒子飘出画面本来就正常），
+   而应是"特效与背景插画始终同倍率、同中心"。
+
+## 做法
+
+新增 `dist/scripts/viewport-fitter.js`（纯函数）与 `SpineController` 的取景维护：
+
+- 参考比例 `16/9`：先让播放器自行解出作者视口 R，换算成参考比例下的可见矩形 V0。
+  **这个比例下与作者设定逐像素一致**。
+- 其它比例：让立绘层的像素缩放**跟着背景的 cover 缩放走**——
+  `V.h = V0.h × coverScale(参考比例) / coverScale(当前比例)`，中心不变。
+  于是背景放大 1.78 倍时，特效也放大 1.78 倍。
+- 应用方式：原地改写 `config.viewport` 的 x/y/width/height 与四个 pad，再调
+  `player.setViewport(动画名)`，并把 `viewportTransitionStart` 推到足够久以前（避免 0.25s 插值拖影）。
+  绝不整体替换 `config.viewport`：`setViewport()` 会无条件读 `config.viewport.animations[name]`，
+  换掉整个对象会在 spine-player 第 14973 行崩溃。
+- 维护时机：挂在 `config.frame` 回调上（它在每帧相机计算**之前**被调用），以画布比例作键——
+  比例没变就是一次浮点比较后返回，比例变了就地重算。
+  `config.success` 用不了：它在 `setViewport` 之前触发，那时 `currentViewport` 还不存在。
+- 预设可用 `framing: "author"` 退回作者原始的 contain 行为。

 ## 验收

- 三种比例下都对拍留档，主体不被裁切、底部不悬空。
- 切换窗口大小时不重建播放器（用 `setViewport`），连续 resize 无内存增长。
+| 项目 | 结果 |
+| --- | --- |
+| 参考比例回归 | kv37 **逐像素 0 差异**；xilian 仅 1/255（浮点末位舍入） |
+| 立绘/背景缩放同步 | 21:9 / 16:9 / 16:10 / 9:16 × 两个预设，**全部精确相等**（离线算式验证 + 渲染实测） |
+| 渲染实测吻合预测 | 三种比例可见矩形与公式预测逐值一致（pads 全 0、base == resolved） |
+| 对拍留档 | `tools/shots/fit/` 下 6 组（2 预设 × 3 比例）改动前后各一套（该目录按仓库约定不入库，可随时重跑重生成） |
+| 不重建播放器 | 9 次改视口 + 连续 20 次压力往返，实例身份标记**从未丢失** |
+| 连续 resize 内存 | 强制 GC 后 7.9 MB → 8.0 MB（增长 **0.04 MB**） |
+| 回到 16:9 可逆 | 取景完全回到原值，无漂移 |
+| 控制台 | 0 报错 / 0 未捕获异常 |
+
+复现：`node .scratch/verify-fitter.mjs`（离线算式）、`node .scratch/test-resize.mjs`（resize 行为）。
+
+## 附带修复
+
+Chromium 会自动请求 `/favicon.ico` 并在控制台留下 404。已在 `dist/index.html` 加
+`<link rel="icon" href="data:," />` 消除，使"0 console 报错"这条验收真正可达成。
@@ -1,17 +1,40 @@
 # 05 WE 属性扩展：音源 combo、fps 限制

-Status: ready-for-agent
+Status: resolved

 ## 内容

-1. **音源（音源作用域已定）**：新增 `project.json` combo `bgm`，列表是所有壁纸音源声明的**并集**（WE 的 combo 是静态列表，只能手工同步）；
-   每档壁纸在自己 `preset.js` 的 `audioChoices` 里声明可选音源。切换壁纸时，若当前音源不属于新壁纸，回落"随预设"。
-2. **fps 限制**：`properties.fps` 经 `applyGeneralProperties` 下发，WE 不会替壁纸限流，需自行实现。
-   实现方式：包裹实例上的 `player.drawFrame`（循环用箭头闭包懒查，因此可以门控）；注意 `config.frame/update/draw`
-   都在下一帧排程之后运行，用它们限不了流。
-3. `setPaused` 暂不实现（WE 会整体冻结进程）；除非用户在 WE 里实测发现音频仍在响。
+1. **音源**：`project.json` 新增 combo `bgm`，列表是所有壁纸音源声明的**并集**
+   （WE 的 combo 是静态列表，只能手工同步），另加一档「随预设」`auto`：
+   `auto` / `zaiduheni`「「再度和你」」/ `xilian`「昔涟」/ `pv37`「版本 PV」。
+   每档壁纸仍在自己 `preset.js` 的 `audioChoices` 里声明可选音源。
+2. **fps 限制**：`properties.fps` 经 `applyGeneralProperties` 下发，WE 不会替壁纸限流，自行实现。
+3. `setPaused` 不实现（WE 会整体冻结进程）。
+
+## 实现要点
+
+- **音源优先级**：用户自填 URL（`audio_file`）> `bgm` 选中的音源 > 本壁纸默认音源。
+  所选音源**只在本壁纸声明过时才生效**；不属于当前壁纸则音频回落本壁纸默认，
+  **选择本身保留**，切回那份壁纸时用户的选择还在。
+- **门控绘制**：包裹实例上的 `drawFrame`。播放器循环写作
+  `requestAnimationFrame(() => this.drawFrame())`——箭头闭包在调用时才读 `this.drawFrame`，
+  所以在实例上换掉它就能接管排程。
+  - 原实现只在**真正绘制**时才排下一帧，而被限流丢掉的帧同样要排，否则循环停摆；
+    因此排程由包装层负责，再让原实现以 `requestNextFrame = false` 调用。
+  - **踩到的坑**：朴素地"距上一帧不足 `interval` 就丢"会把 rAF 抖动放大成整拍丢失——
+    目标 30fps 时落在 33.2ms 的那一帧被判为不足 33.33ms 而丢掉，实测只有 **22.5fps**。
+    改为"留 4ms 容差 + 到期时间按固定步长推进"后精确到 30.0。
+  - **另一个坑**：`if (properties.fps)` 的真值判断会把 `fps: 0`（取消限流）整个吞掉，
+    改判 `!== undefined`。

 ## 验收

- combo 切音源即时生效，且切壁纸时的回落行为正确。
- 设置 30/60 fps 时实际帧率符合，且不影响动画相位推进速度。
+`node .scratch/test-props.mjs`：
+
+| 项目 | 结果 |
+| --- | --- |
+| bgm 切音源即时生效 | ✓（10 项音源断言全过） |
+| 跨壁纸回落 + 选择保留 | ✓ xilian 选「昔涟」→ 切 kv37 回落 pv37 → 切回 xilian 回落默认 |
+| 自定义 URL 优先级最高且不被切壁纸清掉 | ✓ |
+| 限 30 / 20 / 取消限流 | 实测 **30.0 / 20.0 / 60.0 fps** |
+| 不影响动画相位推进速度 | 0.999 / 0.999 / 1.000 倍速（基准 1.000） |
@@ -1,10 +1,34 @@
 # 06 打包 v3 并重新发布

-Status: ready-for-agent
+Status: resolved（第 4 步为人工步骤，待用户执行）

-## 步骤
+## 步骤与结果

-1. `project.json`：`version` 升到 3，更新 `description`（提及新增音源切换等），核对 `properties` 与代码一致。
-2. `preview.gif` 现在 160×160 / 50 帧 / 840 KB——合规（≤256×256、≤1 MB）但超过推荐的 500 KB，重新压缩。
-3. 全量验收：0 死文件、≤35 MB、3 种比例 0 console 报错、预设往返不丢音源设置。
-4. 上传到 Workshop（人工步骤，需要用户操作）。
+1. **`project.json`**：`version` 升到 3；描述新增"可切换各预设自带的背景音乐""自适应窗口比例"；
+   新增 `bgm` combo 与 `bgm_note`。核对：`preset` 的 combo 取值仍是 `xilian` / `kv37`
+   （用户已保存的设置依赖它，绝不能改）。**完成**。
+2. **`preview.gif`**：原 160×160 / 50 帧 / 25fps / 2.0s / **821 KB**，超推荐值 500 KB。
+   重新压缩命令（结果可复现）：
+
+   ```powershell
+   ffmpeg -y -i dist/preview.gif -filter_complex `
+     "[0:v]fps=12.5,split[a][b];[a]palettegen=max_colors=128:stats_mode=full[p];[b][p]paletteuse=dither=none" `
+     -loop 0 .scratch/pv-I.gif
+   Copy-Item .scratch/pv-I.gif dist/preview.gif -Force
+   ```
+
+   （**不能把输入输出写成同一个文件**，ffmpeg 会拒绝；必须先输出到临时文件再覆盖。）
+   即"每 2 帧取 1 帧 + 128 色 + 不抖动"，**逐帧与源帧像素完全相同**（第 k 帧对原第 2k 帧，
+   抽查 0/6/12/18/24 帧全部 SSIM 1.0、max|diff| 0），只是时间采样率减半：
+   160×160 / 25 帧 / 12.5fps / 2.0s / **347 KB**。**完成**。
+   注：减色到 96/64/48 色收效甚微（604/519/474 KB）——体积由帧间变化量主导，不由调色板主导，
+   所以走帧采样率这条路更划算。
+3. **全量验收**（`node .scratch/test-acceptance.mjs`）：**全部通过**
+   - 总体积 **28.52 MB** / 34 个文件（≤ 35 MB）
+   - **0 死文件**
+   - `project.json` 解析正常、version 3、bgm 存在、preset 取值未变
+   - 21:9 / 16:9 / 9:16 三种比例：播放器就绪、可见矩形比例与画布一致、**0 控制台报错 / 0 异常**
+   - 预设往返 10 次：自定义音源与音量 0.2 均未丢失，仍在持续绘制，0 未捕获异常
+4. **上传到 Workshop**：人工步骤，需要用户操作。
+   本次为破坏性较小的重构（16:9 逐像素不变），但 21:9 / 9:16 下构图按设计改变，建议在
+   超宽屏与竖屏各看一眼再发布。
@@ -35,7 +35,7 @@
 | --- | --- | --- |
 | 01 | 资源按 游戏/壁纸 分层，预设拆进各自壁纸目录 | 完成（`09ff322`） |
 | 02 | 体积：音频转 Opus + 图片无损 WebP（105.1 → 28.9 MB） | 完成 |
-| 03 | 健壮性：初始化状态机、死代码、用户级覆盖语义 | 待做 |
-| 04 | 比例适配：按容器比例重算视口 | 待做 |
-| 05 | WE 属性扩展：音源 combo、fps 限制 | 待做 |
-| 06 | 打包 v3 并重新发布 | 待做 |
+| 03 | 健壮性：初始化状态机、死代码、用户级覆盖语义 | 完成（`4662856`） |
+| 04 | 比例适配：立绘层取景跟随背景 cover 缩放 | 完成 |
+| 05 | WE 属性扩展：音源 combo、fps 限制 | 完成 |
+| 06 | 打包 v3 并重新发布 | 完成（上传为待人工执行） |