# ShaderToy 背景皮肤 · 开工前方案复核与决策

> 复核对象：`dsh 桌面版 ShaderToy 实时背景皮肤插件实现方案.md`（下称「原方案」，AI 生成）。
> 依据：DSH **0.2.1-rc.3** 安装包源码（`app.asar`，逐行核验）+ 本机已装真实同类插件 `open-sea-skin@1.2.6`（MIT）+ 外部真实先例（`dsh-video-skin` / `dsh-wallpaper-engine` / `dsh-bg-new` / `dsh-shader-workbench`）。
> 原始研究：`docs/research/01-api.md`（插件机制）、`02-renderer.md`（渲染端）、`03-ecosystem.md`（外部断言核验）。
> 标注：**[核验]** 有源码/实测证据 · **[推断]** 有依据但未实测 · **[待实测]** 必须上机跑。

---

## 0. 一句话结论

**能做，而且比原方案写的更稳。** 原方案的「Runtime 自研 + iframe + 半透明玻璃 + 背景库」四件事全部成立；但 **M0 的注入机制要换**（`webserver/index-inject` → `dsh.client` Client 插件 + Host 静态路由），否则每次改代码都要整机重启、而且拿不到动态主题能力。
剩下唯一没实测的生死点：**把 DSH 界面变半透明后，shader 能不能真的透出来、文字还能不能读** —— 机制已确认可覆盖（AppFrame 的表面颜色全部走 CSS 变量），M0 第一天就能验证。

---

## 1. 原方案：哪些成立、哪些要改

| # | 原方案说法 | 结论 | 修正 |
|---|---|---|---|
| 1 | 「背景层靠 `webserver/index-inject` 注入」 | **真实存在，但不该选** | 桌面版 index 注入表是 **Host 启动时采集一次的 IPC 快照**（`dsh-desktop-host/lib/index.js:342-349` → `main.js:12138/12193/12424-12431`）→ 改一次注入行、装一个新插件都要**整机重启**；Web 端才是每次渲染重收。→ 改走 Client 插件（可热更、能调 theme 服务） |
| 2 | 「注入行不能用 `kind:'script-src'`」 | **半假** | 框架自己就用它注入 bootstrap 批（`dsh-client-modules:494-498`）。真雷是桌面解释器会 `await` 它，加载失败直接 reject boot readiness → 主进程 fatal。→ 结论（别把关键脚本放 script-src）可沿用，理由要改 |
| 3 | 「注入监听器必须在 apply() 里同步注册」 | **成立（有前提）** | 因为桌面注入表只有启动时那一次采集机会 |
| 4 | 「背景层必须挂 body 首子节点，否则破坏 DOM 水合」 | **做法对，理由是错的** | `#root` 是空 div + `createRoot`（不是 hydrate，没有水合）。真实原因：① `#root` 归 React 独占，塞进去会被清掉；② 层叠——`#root > AppFrame` 是 `position:relative`，body 里更早的定位元素先绘制 |
| 5 | 「`dsh-app://` 下 localStorage 不保证可用」 | **可用** | scheme 以 `standard:true, secure:true` 注册（`main.js:11880`），`open-sea-skin`/`better-sidebar` 两个生产插件都在用。仍建议文件为真源，见 D3 |
| 6 | 「音频纹理 512×2，第一行 L 第二行 R」 | **错** | 512×2 是**图像 pass 的音频输入纹理**：row0 = 频谱、row1 = 波形。音频输出是「每像素一个采样 + readPixels 回读」。v1 不做可视化，与输出编码无关 |
| 7 | 「透明化用 `--dsw-alias-*` token」 | **成立，且更好** | 0.2.1-rc.3 里 AppFrame 的表面颜色**全部走 token**（`ui-layout:73`：`.frame{background:var(--dsw-alias-bg-base)}`、`[data-windows-titlebar] .frame{background:var(--dsw-specific-sidebar-fill)}`、`.sidebarCol{...sidebar-fill}`），而 `theme.overrideTokens` 会把覆盖值**内联写到 `body.style`**（`ui-layout:548-569`）→ 滑块可以实时生效，不必学 open-sea-skin 打 `!important` 硬编码类名（其中 2 个 token + 4 个桌面类名在本版根本不存在） |
| 8 | 「三条路线：A 原生 slot / B index-inject / C 扩展」 | **分类失真** | 真实三分法是：官方 `dsh.client` 插件（wallpaper-engine / bg-new / open-sea-skin 原生包）/ `index-inject` 覆盖层（**只有 video-skin 一例**）/ 改源码加 slot。**主流是 client 插件** |
| 9 | 「open-sea-skin 零依赖」 | **错** | 它内置 three.js 0.178 + TSL + 字体（≈1.3MB）。我们的零依赖结论仍然成立，但别拿它当证据 |
| 10 | 「24 个作品基本都是纯程序化单 pass，声音标注准确」 | **未核验** | 本机对 shadertoy.com 恒 403（Cloudflare，实测首页也是 403）。抽样 6 个里 4 个旁证为真、2 个（`fXc3RB`/`ssjyWc`）零证据。→ 24 条必须逐条核验，别写进承诺 |
| 11 | 「许可证 = 默认 CC BY-NC-SA，不能随 MIT 发布」 | **方向对，措辞错** | ShaderToy 条款原文是**作者决定**许可证，**不声明才落到默认 CC BY-NC-SA 3.0**。结论不变：NC/未声明作品不能进 MIT 公开包 |
| 12 | 「预设靠官方 API key 构建期拉取」 | **本机做不到** | 实测：本机 curl/Node 访问 shadertoy.com **全路径 403**（含首页）。API key 路线要另想办法，见 D3 |

另外原方案漏了一个直接竞品：**`dsh-shader-workbench`**（MIT、零运行时依赖、纯 WebGL2、Shadertoy 兼容 + 热重载）——它证明「几百行自研 mini runtime」可行，也说明我们要做出差异（背景/皮肤定位 + 库管理 + 音频 + 可读性）。

---

## 2. 推荐实现方式

### 2.1 四层结构

```
Electron 桌面壳 (dsh-app://app/)
  └─ Host 插件 (Node)  —— 只做两件事：静态资源路由 + 状态读写
       ├─ GET /shader-skin/*            读盘返回 player.html / ui.html / *.js / presets/*.json（no-cache）
       └─ GET|PUT /shader-skin/state    读写 $DSH_HOME/shader-skin.json（临时文件 + rename 原子替换）
  └─ Client 插件 (浏览器, dsh.client)  —— 薄壳(~150 行)，负责挂载与桥接
       ├─ 建 <iframe id=bg-skin>  → body 首子节点, fixed/inset:0/z-index:-1/pointer-events:none
       ├─ 注入玻璃 <style> + ctx.theme.overrideTokens()  ← 滑块改变时重设
       ├─ 悬浮入口（小圆钮 + 面板）与宿主的 mousemove / 可见性 / 主题 双向转发
       └─ 可选：向 settings.section 注册一个"Shader 背景"设置页
  └─ iframe 渲染器 (player.html, 单文件零依赖)  —— 真正干活
       ├─ WebGL2 mini runtime：GLSL 预处理 / uniform / FBO 多 pass / 音频
       └─ postMessage 协议：init / params / mouse / theme / pause / reset → ready / error / stats
```

**关键分工原则：客户端壳越薄越好，所有会反复改的代码都放在 Host 静态路由后面读盘提供。** 理由见 §3。

### 2.2 为什么是这三条

- **为什么不要 index-inject**：桌面注入表是启动快照（§1#1），改一次重启一次；且 Host 侧拿不到 `theme` 服务，做不了动态玻璃。
- **为什么宿主侧要一个 Client 插件**：`theme.overrideTokens` / `slots` / `locale` 都是 **Client 服务**，只有 client 半能用；client 半还能直接操作 DOM（`open-sea-skin` 生产先例）。
- **为什么渲染器放同源 iframe**：编译失败 / JS 异常 / 内存泄漏止于子文档，`location.reload()` 即重启；player 可以独立打开调试。（**注意**：iframe 隔离不了 GPU 进程崩溃——这个风险要单独兜，见 §7。）
- **为什么零依赖自研**：ShaderToy 代码本来就是 GLSL 文本 + 标准 uniform，three.js 帮不上忙还带 1MB+；不选 WebGPU 是因为它只吃 WGSL，转译链不可控，且 Electron/Windows 上可用性不如 WebGL2。

### 2.3 透明化怎么做（项目生死点）

三步，全部有源码依据：

1. **`ctx.theme.overrideTokens('shader-skin', { '--dsw-alias-bg-base': {light, dark}, '--dsw-specific-sidebar-fill': {light, dark}, … })`**
   值必须是 `{ light, dark }` 成对字符串（否则运行时抛教学错）。它把值内联到 `body.style`，能压过基础样式表，从而让 AppFrame / 侧栏 / 中栏变半透明。
2. **`<style>` 补丁**（只在 token 表达不了的地方）：弹层/对话框保持不透明、必要时补 titlebar 条与 rightbar 列的规则。
3. **`<iframe>` 的透明度**用 `opacity` 一个值搞定，不要用多层覆盖色凑。

> **[已实测，结论见 §9.3-9.4]** 把 `--dsw-alias-bg-base` + `--dsw-specific-sidebar-fill` 设成 rgba 半透明的做法**行不通**：外壳是十几层嵌套表面、每层都画同一个 token，alpha 相乘后背景几乎全黑，且层数随页面变化、无法用固定补偿救回。落地版改成：两个 token 设**全透明**，暗色滤镜由播放器在着色器输出上画唯一一层（`tintMix` = 玻璃不透明度），滑块只发 `params`、不碰 token。
> 与 open-sea-skin 的差异：**不覆盖 `--dsw-alias-bg-layer-1/2/3`**（卡片、输入框保持实体）→ 可读性最稳。

### 2.4 持久化

- 真源：**`$DSH_HOME/shader-skin.json`**，Host 用 `node:fs` 写（写临时文件 + rename），Client 走同源相对路径 `fetch('shader-skin/state')`。
- 桌面下 `dsh-app://app/shader-skin/...` 会被 shell 转发到 Host 的 HTTP 服务（`main.js:12406-12413`），所以同源 fetch 成立；生产先例 `dsh-better-sidebar` 的 `/sidebar/api/*`。
- **不要**用 `__DSH_TRANSPORT__.streamBaseUrl` 发 HTTP（那是 Host 真实 origin，跨源且无 CORS 头）。
- localStorage 只做缓存（面板位置、上次 tab），不作为库的真源——清站点数据/重置 profile 会丢。

### 2.5 设置界面（最终形态：侧边栏 → 整页）

| 入口 | 承载 | 状态 |
|---|---|---|
| 左栏「Shader 背景」→ `main` 整页 | 全部：开关、作品切换、玻璃/亮度/模糊/分辨率/帧率/速度/音量、背景库（导入/改名/删除） | ✅ 已实现（原计划的「右下角小圆钮 + 浮层面板」已废弃，见 §9.5） |

> 整页 iframe（`/shader-skin/panel.html?mode=main`）内容仍走 Host 静态路由 → 迭代只需刷新，不用重启。**不用** `settings.section`：`sidebar.panellist` + `main` 更接近原生面板的交互（点左栏一行、主区域整页），也不需要写 React 组件。

---

## 3. 开发循环：这是最大的效率优化

DSH 各层的热更能力是**分层的**（[核验]）：

| 改动位置 | 生效方式 | 代价 |
|---|---|---|
| Host 静态路由后面的 `player.html` / `*.js` / `*.css` / `*.json`（**读盘 + no-cache**） | **刷新页面即可** | ≈1 秒 |
| Client 插件 `client.js` 内容 | host 每 500ms 轮询文件 → SSE `/plugins/events` → 浏览器热替换 | 免重启（桌面端 SSE 是否通 **[待实测]**，不通就整机重启） |
| Host 插件 `index.js`（路由/apply 逻辑） | Host HMR 可能热更 | 若失效则整机重启 |
| 新增/启用插件、改注入行 | **整机重启** | 15 秒 |

**结论**：把渲染器、UI、预设全部放进 Host 静态路由，插件本体（Host+Client）写成一次成型、尽量不动的薄壳。**日常改 shader/调样式只刷新页面**，这是本项目最重要的工程决策。

---

## 4. 决策（✅ 已定稿 2026-10-26）

**D1 = A**（Client 插件 + Host 静态路由 + iframe）·
**D2 = A**（只透底壳，卡片与输入框保持实体）·
**D3 = A**（用户浏览器 Export JSON → 本地文件夹自动导入；M0/M1 先用自写 shader）·
**D4 = A**（合并为 4 个滑块：玻璃不透明度 / 模糊 / 缩放 / 速度，另有音量+静音）·
**D5 = A**（按 M0→M1→M2，音频留 M2）·
**D6 = A**（装完默认开启第一个背景，默认低亮度 + 30fps）。

以下为决策时的备选与理由，保留备查：

| # | 决策 | 选项 | 我的推荐 | 定稿 |
| **D1** | 架构路线 | A. Client 插件 + Host 静态路由 + iframe / B. 纯 index-inject 覆盖层（video-skin 路线，零 client 半）/ C. 纯 Client 插件（srcdoc，无 Host 半，无文件持久化） | **A**：唯一同时满足「动态玻璃」「可热更」「能存文件」的路线；B 每次改代码要整机重启；C 无法做库的持久化与静态资源迭代 | ✅ A |
| **D2** | 玻璃强度 | A. 只透「壳」（AppFrame/侧栏底），卡片与输入框保持实体 / B. 卡片、输入框也半透明（全玻璃，更好看但可读性风险）/ C. 两档，用户自己切 | **A 起步**，C 作为 M3 增强。可读性 > 视觉是第一约束，slider 下限要锁死（如玻璃不透明度 40%–90%） | ✅ A |
| **D3** | 24 个预设怎么来（本机打不开 shadertoy） | A. 你在浏览器里逐个 **Export 成 JSON** → 放到本地文件夹，插件先扫本地再入库 / B. 你给 API key，做一个「浏览器侧导入助手」页面在你浏览器里跑（绕过本机 403）/ C. 只用自写示例 shader，24 个以后再说 / D. 手工复制粘贴 24 段代码 | **A 为主 + B 兜底**。理由：本机 curl/Node 对 shadertoy.com 全路径 403（实测），构建期 API 拉取在你这台机器上不可行；但你的浏览器大概率能开，导出 JSON 一次性最省事。C 会让 M0/M1 先跑起来（**M0/M1 一律用自写 shader**） | ✅ A |
| **D4** | v1 参数取舍 | A. 合并「透明度 + 压暗」→ 1 个「玻璃不透明度」滑块，共 4 个（玻璃/模糊/缩放/速度）+ 音量 / B. 保持原定 5 个独立滑块 | **A**：透明度和压暗本质是同一件事（字底下有多黑），两个滑块会产生互相打架的无效组合 | ✅ A |
| **D5** | 音频优先级 | A. 按 M0→M1→M2（先画面，后声音）/ B. 音频提前（24 个里约一半带音乐）/ C. v1 不做音频 | **A**：音频是高风险模块（readPixels 卡顿、爆音、音画同步），先把画面与库跑通；M2 单独攻 | ✅ A |
| **D6** | 默认状态 | A. 装完默认开启第一个背景（低亮度）/ B. 默认关闭，等用户主动开 | **A**：装皮肤就是为了看，但默认玻璃调厚 + 帧率 30fps（省电） | ✅ A |

### 4.1 由决策直接得出的实现口径

- 玻璃只覆盖 `--dsw-alias-bg-base` + `--dsw-specific-sidebar-fill`（+ 必要的 `<style>` 补丁），**不动** `bg-layer-1/2/3`，让卡片/输入框保持实体。
- 参数：`glass`（0.40–0.90，映射桌面壳 alpha）、`blur`（0–12px，默认 0）、`scale`（0.5–2 + 「适应全屏」）、`speed`（0–2，默认 1）、`volume`（0–1）+ `muted`。
- 预设来源：M0/M1 随包内置 2–3 个**自写** shader（MIT）；`$DSH_HOME/shader-skin/presets/*.json` 目录扫描 → 你导出的 Shadertoy JSON 丢进去即入库；公开包不含任何 ShaderToy 作品代码。
- 音频：M2 才动，验收必须用一个**确认有 sound pass** 的作品。

---

## 4.2 原表（备查）

| # | 决策 | 选项 | 我的推荐 |
|---|---|---|---|
| **D1** | 架构路线 | A. Client 插件 + Host 静态路由 + iframe / B. 纯 index-inject 覆盖层（video-skin 路线，零 client 半）/ C. 纯 Client 插件（srcdoc，无 Host 半，无文件持久化） | **A**：唯一同时满足「动态玻璃」「可热更」「能存文件」的路线；B 每次改代码要整机重启；C 无法做库的持久化与静态资源迭代 |
| **D2** | 玻璃强度 | A. 只透「壳」（AppFrame/侧栏底），卡片与输入框保持实体 / B. 卡片、输入框也半透明（全玻璃，更好看但可读性风险）/ C. 两档，用户自己切 | **A 起步**，C 作为 M3 增强。可读性 > 视觉是第一约束，slider 下限要锁死（如玻璃不透明度 40%–90%） |
| **D3** | 24 个预设怎么来（本机打不开 shadertoy） | A. 你在浏览器里逐个 **Export 成 JSON** → 放到本地文件夹，插件先扫本地再入库 / B. 你给 API key，做一个「浏览器侧导入助手」页面在你浏览器里跑（绕过本机 403）/ C. 只用自写示例 shader，24 个以后再说 / D. 手工复制粘贴 24 段代码 | **A 为主 + B 兜底**。理由：本机 curl/Node 对 shadertoy.com 全路径 403（实测），构建期 API 拉取在你这台机器上不可行；但你的浏览器大概率能开，导出 JSON 一次性最省事。C 会让 M0/M1 先跑起来（**M0/M1 一律用自写 shader**） |
| **D4** | v1 参数取舍 | A. 合并「透明度 + 压暗」→ 1 个「玻璃不透明度」滑块，共 4 个（玻璃/模糊/缩放/速度）+ 音量 / B. 保持原定 5 个独立滑块 | **A**：透明度和压暗本质是同一件事（字底下有多黑），两个滑块会产生互相打架的无效组合 |
| **D5** | 音频优先级 | A. 按 M0→M1→M2（先画面，后声音）/ B. 音频提前（24 个里约一半带音乐）/ C. v1 不做音频 | **A**：音频是高风险模块（readPixels 卡顿、爆音、音画同步），先把画面与库跑通；M2 单独攻 |
| **D6** | 默认状态 | A. 装完默认开启第一个背景（低亮度）/ B. 默认关闭，等用户主动开 | **A**：装皮肤就是为了看，但默认玻璃调厚 + 帧率 30fps（省电） |

---

## 5. 优化空间（按收益排序）

1. **开发循环**（§3）：静态资源读盘 + no-cache → 刷新即迭代；插件壳一次成型。**收益最大**。
2. **玻璃用官方 `theme.overrideTokens`** 而不是 open-sea-skin 那套 `!important` + 硬编码 CSS-module 类名：更稳、更短、切亮暗主题自动跟随、滑块实时生效。
3. **音频大块回读**：512 采样逐块 = 每秒 86 次同步 `readPixels`（每次强制 flush GPU）。改成 **4096 采样/块（≈10.8 次/秒）+ 双通道 16bit 打包 + 500ms 预缓冲 + AudioBufferSourceNode 前瞻调度** → 回读开销降一个数量级，且背景音乐不怕延迟。AudioWorklet 留作 v2。
4. **模糊分级**：低分辨率渲染只给「柔」（省填充成本，scale 0.5 → 片元 25%），CSS `blur()` 才给「糊」；blur=0 时**完全不加 filter**（不设 will-change）。默认 0。
5. **可读性在渲染器内部解决**：在 player 里做 dim/tint 混合（暗色乘 ~0.5、亮色向 `#ececec` 混），零额外合成成本；不用额外叠覆盖层。
6. **背压与省电**：可见性暂停、失焦降到 30fps、电池模式 DPR 1.0、`prefers-reduced-motion` 进静态模式、自适应分辨率（EMA 滞回）、软渲染（SwiftShader/WARP）强制降档。
7. **预设按需加载**：shader 代码拆成 `presets/*.json` 单条 fetch，不进 JS bundle —— 库再大也不拖慢启动，且方便你随时替换 .json。
8. **切换零白屏**：编译完成前保留上一帧，失败回退旧作品；编译用 `KHR_parallel_shader_compile` 轮询，避免卡主线程。
9. **导入即体检**：粘贴/导入时在 1×1 离屏 WebGL2 上真编译 + 静态扫描（外部纹理 / cubemap / 键盘通道 / `mainVR` / `#define iTime` / ES3 保留字）→ 直接给「能跑 / 需要图片输入不支持 / 高负载将自动降档」的结论，而不是等用户点了才炸。
10. **崩溃兜底**：iframe 隔离不了 GPU 进程崩溃 → 崩溃计数持久化，连续 2 次自动进安全模式（关背景 + 提示），并提供一键关闭。

---

## 6. 修订后的里程碑

| 里程碑 | 内容 | 验收（可观测） |
|---|---|---|
| **M0 跑通**（~1 天） | bundle 骨架（Host 路由 + Client 薄壳）+ iframe + 单 pass WebGL2 runtime + 玻璃 token + 一个自写 shader | ① 装完（重启一次）背景出现；② 宿主可正常聊天/输入；③ 洋红 debug 层 + `elementsFromPoint` 网格证明背景不拦截任何指针；④ 截图对比度 p5 ≥ 4.5；⑤ 改 player 文件 → 刷新即生效 |
| **M1 背景库**（~2–3 天） | 数据模型、库列表/切换/改名/删除/恢复内置、粘贴导入 + 静态体检、`$DSH_HOME` 持久化、4 个滑块 + 音量占位 | 刷新后设置保留；改名/删除/恢复生效；非法 shader 给明确报错不崩 |
| **M2 音频**（~2–3 天） | mainSound 编译 + 大块回读 + WebAudio 前瞻调度 + GainNode 音量/静音 + 每背景记忆 + 自动播放兜底 | 用一个**确认有 sound pass** 的作品验收；音量/静音即时生效；Electron 免手势有声，浏览器静音兜底 + 「开声音」 |
| **M3 打磨** | 设置页、（可选）双档玻璃、多 pass、外部纹理、预设批量导入、性能打磨、README / MIT 打包 | 24 个作品逐条过（能跑的进白名单，不能跑的给原因）+ 全新环境安装验证 |

### 6.1 M0 施工单（文件级，可直接照做）

包名 `dsh-shadertoy-skin`（MIT，`private: true` 私有构建），目录结构：

```
dsh-shadertoy-skin/
├─ package.json          dsh.bundle.patch + dsh.client{platform:'web'} + exports["./client"]
├─ cordis.patch.yml      insert 一行 {id: shadertoy-skin, name: dsh-shadertoy-skin}
├─ index.js              Host 半：ctx.webServer 前缀路由 /shader-skin（读盘 no-cache）
│                        + GET/PUT /shader-skin/state（$DSH_HOME/shader-skin.json，原子写）
├─ client.js             Client 半（lazy-CJS，window.__ModuleLoader__.load）
│                        ├─ 背景 iframe（body 首子节点, z-index:-1, pointer-events:none）
│                        ├─ 玻璃：theme.overrideTokens + 少量 <style>
│                        ├─ 悬浮按钮 + 面板（4 滑块 + 音量占位 + 背景切换）
│                        ├─ 指针/可见性/主题转发（postMessage）
│                        └─ 全部资源走 ctx.effect 清理
├─ locale/{zh,en}.json   插件管理器里的显示名/描述
├─ icon.svg              插件图标
└─ native-dist/
   ├─ player.html        单文件 WebGL2 runtime（M0：单 pass + 全 uniform + 错误面板 + ?debug=bg）
   ├─ ui.js / ui.css     （M1 起拆出，M0 可内联在 client.js）
   └─ presets/*.json     自写 shader（M0：1 个；M1：2–3 个）
```

M0 施工顺序（每步都可独立验证）：

| 步 | 做什么 | 验证 |
|---|---|---|
| M0-A | Host 半：路由 + `player.html` 假页面（洋红整屏）+ state 读写 | 浏览器直接开 `http://127.0.0.1:<port>/shader-skin/player.html` 能看到洋红（**不需要重启**，Host 热更若不生效才重启） |
| M0-B | Client 半：挂 iframe + 玻璃 + `?debug=bg`，用 `elementsFromPoint` 网格验证不拦指针 | 装插件（**需整机重启一次**）后：背景出现、聊天可操作、网格命中率 0% |
| M0-C | player 接真 shader（自写），uniform + resize + 错误面板 | 画面在跑；切到窗宽变化不崩；故意写错 shader 得到可读报错 |
| M0-D | 4 滑块打通 client → postMessage → player / glass token | 拖滑块即时生效；刷新后保留（state 文件） |
| M0-E | 收尾验收：截图对比度 p5 ≥ 4.5、亮/暗两套、弹层可读、隐藏暂停 | 逐条截图存 `docs/verify/M0/` |

**风险最高的一步是 M0-B**（玻璃 + 层叠），所以 A 步先做、B 步尽早做；M0-C/D 是纯工程。

### 6.2 M0 进度（2026-10-26）

按「先写渲染器本地跑」推进，**渲染器已在本地跑通并用无头 Edge 回归**（不涉及安装、没动 DSH 环境）：

| 产出 | 状态 |
|---|---|
| `native-dist/player.html`（单文件 zero-dep WebGL2 runtime） | ✅ 跑通 |
| `native-dist/presets/{aurora,flow}.glsl` + `index.json` | ✅ 2 个自写 shader（MIT） |
| `tools/dev-server.mjs`（本地复刻 Host 路由，no-cache） | ✅ |
| `docs/renderer-notes.md`（URL 参数 / postMessage 协议 / 已知限制） | ✅ |
| `docs/verify/M0/*.png`（aurora 默认/全亮、flow、洋红 debug 层） | ✅ |

回归矩阵（无头 Edge + SwiftShader，`--dump-dom` 读诊断）：`aurora`→es3 ✔ / `flow`→es3 ✔ / `dev/legacy`（`gl_FragColor`+`void main` 改写）→es3 ✔ / `dev/es1`（`gl_FragData` 强制回落）→es1 ✔ / `dev/broken`（语法错）→错误面板含行号 ✔ / 不存在的 preset → 明确报错 ✔ / 两次不同虚拟时间的截图不同 → 时间轴在走 ✔ / `scale=0.5` → 缓冲尺寸减半 ✔。

顺带验证到一个真实坑：GLSL ES 3.00 里 `patch` 是保留字，静默掉到 ES1 才跑通 —— 已写进 README 的已知取舍。

下一步：M0-A（Host 半路由 + 状态文件）→ 安装后不重启即可在浏览器验证 `/shader-skin/player.html`；再 M0-B（Client 薄壳 + 玻璃 + 层叠穿透）需要重启一次客户端。



---

## 7. 风险登记册

| # | 风险 | 概率 | 处置 |
|---|---|---|---|
| R1 | 玻璃化后文字不可读 / 宿主某层被上游改回不透明 | 中 | M0 第一天实测；token 为主 + `<style>` 补丁；不行就降玻璃强度或只透局部；**绝不为了背景牺牲可读性** |
| R2 | 层叠假设被宿主 DOM 变更打破（背景被盖住） | 中 | 首选 `z-index:-1`（video-skin 实测可行），备选 `z-index:0` + `#root{z-index:1}`；M0 用网格命中检测 + 截图验收 |
| R3 | 24 个作品的真实结构未知（多 pass / 外部纹理 / 键盘 / 声音签名） | 高 | 逐条核验放 M1（导入即体检）；失败的作品给原因，不进白名单 |
| R4 | `readPixels` 同步回读导致周期性卡顿/爆音 | 中 | 4096 大块 + 500ms 预缓冲；仍不行上 PBO + fence 异步回读；再不行 AudioWorklet |
| R5 | GPU 进程崩溃 / TDR 连累整个 DSH（iframe 隔离不了） | 低中 | 看门狗（单帧 >2s）、崩溃计数、连续 2 次进安全模式、一键关闭 |
| R6 | 桌面端 client 插件热更/免重启行为与预期不符 | 中 | M0 实测一次；兜底「整机重启 15 秒」可接受 |
| R7 | 许可证：NC/未声明作品不能进 MIT 公开包 | 确定 | 公开版只含自写 shader + 显式 CC0/MIT 作品；24 个作品走「本地导入」不进包 |
| R8 | DSH 版本升级改内部 DOM/类名 | 中 | 只用稳定锚点（token、`[data-platform]`、`[data-shell-overlay]`），不用 CSS-module hash / `:has()` 整树匹配；升级后 M0 验收脚本可回归 |

### 明确不做（避免跑偏）

- ❌ 不在 v1 做 iChannel 音频可视化回馈（原 C9 决定保留）。
- ❌ 不用 three.js / WebGPU / 任何 npm 运行时依赖。
- ❌ 不接管键盘、不做全屏游戏式交互（原 C6 决定保留）。
- ❌ 不把 index-inject 当配置/热更通道。
- ❌ 不为了背景效果牺牲文字可读性。

---

## 8. 证据索引

- 插件机制 / 生效语义 / 持久化 / 主题 / 设置槽位 / 红线判决：`docs/research/01-api.md`
- 渲染端设计 / GLSL 兼容 / 多 pass / 音频 / 层叠 / 性能 / 兼容性体检 / 工作量（~1450 行，M0 约 450 行）：`docs/research/02-renderer.md`
- 同类插件 / ShaderToy API / 许可证 / 24 作品抽样 / 生态数据核验：`docs/research/03-ecosystem.md`
- 生产级参考实现（已装本机）：`%DSH_HOME%\profiles\desktop\node_modules\open-sea-skin\`（`plugin/index.js` Host 路由、`plugin/client.js` client 半全套）
- 官方模板副本：`docs/research/templates/decoration/`
- asar 解包工具（研究用）：`tools/asar-extract.ps1`

---

## 9. 实施记录（M0 → M2 完成）

### 9.1 完成内容

| 里程碑 | 内容 | 验证 |
|---|---|---|
| M0 | 插件骨架（Host 静态路由 + Client 薄壳）+ 零依赖 WebGL2 播放器 + 玻璃 + 设置页 | 安装后背景渲染、聊天可用；`/shader-skin/health` 200 |
| M1 | 背景库（内置 + 我的背景：切换/改名/删除）+ 三种导入（粘贴 / 文件 / 本地目录）+ 每背景 `overrides` + 深浅色适配 + 自定义下拉（修掉系统白色弹层） | `npm run test:renderer` 22 项、`npm run test:host` 30 项 |
| M2 | `mainSound` → 4096×1 RGBA8（16bit 打包）→ `readPixels` → WebAudio 前瞻调度 + Gain/限幅；音量/静音实时；每背景记忆 | `npm run test:audio` 16 项；实测 44100Hz、11 块/s、peak 0.281、rms 0.113 |

### 9.2 真实作品实测

- 用户提供 **Seascape（TDM，CC BY-NC-SA 3.0）**：本地导入 `$DSH_HOME/shader-skin/presets/seascape.glsl`，在播放器里 `?preset=local/seascape.glsl` 直接 ES3 编译通过、画面正确（`docs/verify/seascape.png`）。**该作品不进包、不进仓库**，只作为本机用户背景（已写入 `$DSH_HOME/shader-skin.json` 并设为当前背景）。

### 9.3 卡死 / 失效复盘（重要，别再踩）

桌面端前端两次被卡死，另外还有两次「滑块像死的」——根因有四条，三条出在 **client 半** 的框架用法上：

1. **`:has()` 锚定整树**：玻璃补丁用过 `body #root div:has(> [data-shell-overlay])` 这类选择器。切换侧边栏面板时 Chromium 触发整棵 `#root` 的样式失效重算，界面像死机。→ 已删除所有 `:has()`。
2. **主题 observer 反馈环**：监听 `body[data-ds-dark-theme]` 时，回调里调用 `applyGlass()` → `theme.overrideTokens()` 会发 `theme/change` → presenter 重新写一遍该属性 → 再次触发 observer → **无限循环烧 CPU**。改代码触发热重载后尤其明显。→ 回调只做「值真的变了才转发」，绝不在回调里改 token；玻璃 token 现在只在启动时写一次，滑块完全不再碰 token。
3. **面板消息全被丢弃（「滑块失效」真凶）**：`postMessage` 的事件里 `event.source` 是 iframe 的 **`contentWindow`（WindowProxy）**，而 client 半把 **`<iframe>` 元素**存进 `panelFrames`，再 `panelFrames.has(event.source)` 判断——永远 false。于是设置页发来的 `params` / `preset` / `audio-resume` 全被静默丢掉：滑块拖了没反应、切作品不生效，但**状态文件照常保存**（那是面板自己 PUT 的），看起来像「设置保存了却不起作用」。→ 改为按 window 存（`panelWindows`），发送时统一 `target?.contentWindow ?? target`。
4. **半透明 token 层层相乘（「背景太黑」真凶）**：外壳并非两层表面——AppFrame、中列、各页面根、Windows 标题条等**十来个嵌套容器**都画 `var(--dsw-alias-bg-base)`。每层 alpha 0.225（对应 glass=40%）时只剩 `0.775^n` 的背景可见，实测亮色海面被压到约 7% 亮度，看着就是「一片黑 + 隐约波纹」。→ 玻璃模型换成一层的方案，见 9.4。

**安全阀**：`$DSH_HOME/shader-skin.safe` 存在时，client 半跳过所有注入 `#root` 的 UI（只留背景层）；Host 暴露 `/shader-skin/safe-mode` 供读取。

### 9.4 玻璃模型 v2：外壳全透明 + 播放器画唯一一层滤镜

旧模型（`--dsw-alias-bg-base` / `--dsw-specific-sidebar-fill` 设成半透明 rgba，再按「两层」做 `a = 1 - sqrt(1 - glass)` 补偿）在真实 DOM 上必然过暗，因为层数不是 2 而是十几层，且数量随页面结构变化，**参数无法补偿未知层数**。

新模型把两件事拆开：

1. **外壳表面**：两个 token 直接设成全透明（`rgba(9,12,16,0)` / `rgba(255,255,255,0)`），背景层因此成为唯一的底；token 只在启动时写一次，拖滑块不触发 `theme/change`，没有重排风暴风险。
2. **唯一的滤镜**：由播放器在着色器输出上做一次 `mix(color * brightness, veil, glass)`（`dim` + `tint` + `tintMix`），一层合成、与 DOM 深度无关。`glass` 滑块 = 这层滤镜的不透明度；`brightness` 滑块 = 画面亮度乘数（0.3–1.8）。

配套改动：

- 播放器 `dim` 上限从 1.0 放到 2.0，并新增 `lookExplicit`：父页面一旦发过显式 look，主题消息不再把它重置成「按主题猜的默认压暗」；
- 主题消息提前到 `init` 之前发，初始化参数最后到达，保证「显式 look 赢」；
- 设置页新增「背景亮度」滑块，`defaults.json` 的 `glass` 默认 72→60、新增 `brightness: 100`。


### 9.5 侧边栏原生入口（改为整页）

`sidebar.panellist` + `main` 的注册形态按真实先例核对（`slots.inject(key, () => slots.register({name, id|key, order, label}, Component))`）。第一版曾把弹窗面板嵌进 `main` 且带着上面两条卡死根因，导致点侧边栏就卡死；两条根因修掉后改为：

- **去掉悬浮弹窗**（右下角圆钮整个移除，缩小了失败面）；
- 侧边栏一行「Shader 背景」→ `main` 面板渲染 `/shader-skin/panel.html?mode=main`，在**主区域整页展示**（页头 + 参数 / 背景库两个页签），iframe 用 `position:absolute; inset:0` 填满主列（不依赖父容器百分比高度）；
- 仍由 `ENABLE_SIDEBAR_ENTRY` 常量控制，`$DSH_HOME/shader-skin.safe` 可一键跳过注册。

### 9.6 交互细化：iMouse 拖拽 + 代码页（v0.2.0）

**iMouse 只在拖拽时驱动，而且必须从「空白处」按下**：旧版把每个 `pointermove` 都转发给播放器，鼠标划过界面背景就跟着搅动，抬手后 `iMouse.xy` 还在动。现在的判定分两层：

1. `pointerdown` 的命中目标若落在 DSH 自己的控件/可选文字上（`button/a/input/textarea/select/summary/label/[contenteditable]/[role=button|tab|menuitem|option|dialog|listbox]/[data-shell-overlay]/[data-rightbar-col]/[data-shell-bottom]`，或祖先链上 `user-select: text`）→ 整次拖动不接管背景；
2. 拖动过程中一旦出现文本选区（`getSelection().type === 'Range'`，即复制/选中回复）→ 立即中止并丢弃这一帧的鼠标消息。

按下只记录 anchor，真正移动才开始转发；松开/取消/失焦 → 发**一条** `[…, -|anchor|]`，让着色器按 ShaderToy 语义看到 `iMouse.z < 0` 的「已松手」状态。

**卡片透明度三档（`panels`）**：外壳（`bg-base` / `sidebar-fill`）永远全透明，但卡片、代码块、弹层、菜单、输入框默认仍是实体色，背景透不进去。新增 `panels` 参数 → 覆盖 `--dsw-alias-bg-layer-1/2/3/4`（alpha 0.62 / 0.22）与 `--dsw-alias-bg-overlay`、`--dsw-specific-menu`、`--dsw-specific-input-major`（alpha 层值 + 0.32，保证弹层/菜单还能读）。三档 = `opaque`（不覆盖，默认）/ `half` / `clear`。这一项会真的重设 token（会发一次 `theme/change`），所以按「token 集合签名变化时才重新发布」处理：拖玻璃/亮度滑块不会触发重设，只有切换档位才会。

**代码页（第三个页签）**：显示**当前正在运行**作品的 Image / Sound 源码，可直接编辑 →「保存并运行」（Ctrl/⌘+S 同效）：

- 保存 = 写 `$DSH_HOME/shader-skin.json` → 通知 client 重新 `sendInit` → 播放器重新编译；编译错误（带 GLSL 行号）显示在按钮下方；
- 内置作品只读：保存时自动 `addEntry` 出「<原名>（我的副本）」并切过去，包内文件不动；
- 「放弃修改」重新读取已保存版本。

顺带修掉一个潜伏的竞态：`setActive` 以前先发 `preset` 消息、320ms 后才防抖保存。client 收到 `preset` 会 `reloadState()` 重新读盘——新条目**还没落盘**，于是 `resolvePreset` 找不到它、回落到第一个内置作品，出现「切到新导入的作品却显示极光」。现在 `setActive` / 删除 / 导入都先 `saveNow()`（立即 PUT）再发消息。

**已知坑：`precise` 在 WebGL2 里不合法**。ShaderToy 上防止驱动 FMA 收缩、让共享晶格点同哈希的写法用 `precise float h = …`，但 `precise` 是 GLSL 4.0 / ESSL 3.20 的限定符，WebGL2 只有 ESSL 3.00，实测报 `ERROR: 0:39: 'precise' : undeclared identifier`（ES3/ES1 都挂）。等价修法是**整数哈希**（`ivec2 + uint` 位混合），不需要限定符，且共享晶格点天然同哈希。用户的海面（Seascape）已按此替换 `hash`/`noise` 两份函数并验证 ES3 编译通过、画面正常。

### 9.7 启动自愈：为什么「每次重启都要手动关掉再打开插件」

**根因（客户端插件启动竞态）**：桌面端 client 插件按 loader 行**并发激活**（`modules.entries.start` 之后 `await loader.await()`，每个 fiber 只等自己在 `inject` 里声明的依赖）。我们 client 半声明 `inject: []`，所以可能比 `theme` / `slots` 这两个服务**先**激活。旧代码在 effect 建立时一次性取值：

```js
const theme = ctx.get('theme')   // 此时可能还是 undefined
const slots = ctx.get('slots')
```

服务晚到之后这个引用永远是 `undefined` → `applyGlass()` 直接 return（外壳 token 没被覆盖 → **背景被不透明的壳挡住，看起来像插件没启动**），`registerSidebar()` 也直接 return（**左栏没有入口**）。而手动关掉再打开插件会重新跑一遍 `apply`，那时服务都就绪 → 一切正常。这就是「每次重启都要手动开关一次」的全部原因。

**修法（三层）**：

1. **不再缓存服务引用**：`service(name)` 每次 `ctx.get(name)` 现取，`applyGlass()` / `registerSidebar()` 里都现取 `theme` / `slots`；`require('react')` 也做成惰性重试（模块表可能后到）。
2. **启动时等一等**：`waitForService('theme' | 'slots', 15s)` 轮询（50ms），等到再应用玻璃、注册侧栏，不再依赖「碰巧先激活」。
3. **有界自愈**：`verifySurface()` 在启动后 0/250/700/1500/3000/6000/10000ms 各跑一次，外加首次 `focus` / `pointerdown` / 回到前台时各跑一次，检查并修复：
   - 背景 iframe 不存在或被壳重绘弄掉 → 重建；
   - 玻璃 token 被 body 样式重置覆盖 → 重新应用（`tokensIntact` 逐 token 检查 inline 值是否存在）；
   - 播放器没收到 init / 没上报 `ready` → 重发 init（上限 4 次、3s 重试）；`ready` 消息现在会被记录；
   - 侧栏行当时因 `slots` 缺失没注册上 → 补注册。
   这些检查只做「缺了才补」，不会形成 `theme/change` 循环（自愈共 7+3 次后稳定）。

### 9.8 两个「改了没用」的 bug：参数白名单 + 声音签名

**① `brightness` / `panels` 保存后丢失（假的「能保存」）**：面板修改后 `PUT /shader-skin/state` **返回 200**，但 Host 的 `sanitizeParams` 里 `PARAM_KEYS` 是手写白名单（`enabled/glass/blur/scale/fps/speed/volume/muted`），新加的 `brightness` 与 `panels` 不在里面 → 服务端静默丢弃，前端本地看着改了、重启/重开面板就回默认。修法：

- 白名单加上 `brightness`（number）与 `panels`（枚举 `opaque|half|clear`，非法值丢弃）；
- `sanitizeEntry` 的 `source` 枚举补上代码页用的 `edit`；
- `tools/host-route-test.mjs` 增加往返断言（brightness 135 / panels half 必须原样读回，非法值必须被丢弃）。

教训：**前端「保存成功」只代表 HTTP 200，不代表字段被接受**——新的参数键必须同时改 Host 白名单。

**② 声音 pass 编译失败（保存了但没声音）**：用户粘的是 ShaderToy 的 `vec2 mainSound( in int samp, float time )`，而播放器包装器只会拼 `vec2 mainSound(float)` 的调用 → 编译报 `'mainSound' : no matching overloaded function found` + `'=' : dimension mismatch`，`setSound` 失败、静音。ShaderToy 音频 pass 实际有四种签名，现在按声明自动选择：

| 声明 | 包装器调用 |
|---|---|
| `vec2 mainSound(float t)` | `mainSound(st_t)` |
| `float mainSound(float t)` | 单声道，复制到 L/R |
| `vec2 mainSound(int samp, float t)` | `mainSound(st_samp, st_t)` |
| `float mainSound(int samp, float t)` | 单声道 + 采样序号 |

`st_samp = int(floor(mod(st_t * iSampleRate, 2147483000.0)))`（避开 int 溢出）。同时把完整编译日志打到 console，`diag` 里显示前 3 行，以后声音编译失败可诊断。新增夹具 `native-dist/presets/dev/mono-sound{,-sound}.glsl` 与 audio-smoke 断言，CI 覆盖签名回归。

**③ autoplay 拦截**：即使签名对了，浏览器仍可能让 `AudioContext` 处于 `suspended`。client 半现在记录播放器上报的 audio 状态，在**界面任意一次 pointerdown / keydown / focus** 时发 `audio-resume` 自动解锁；面板提示也改成「点一下界面任意位置解锁」。

### 9.9 输入栏透明、循环播放、音乐只播一次、品牌蓝与可调代码框

**① 聊天输入栏还是实心**：`panels` 覆盖的 token 列表里少了聊天输入区真正用的那两个 —— `--dsw-alias-bg-module-platform`（composer / 编辑器表面，`composerSeat` 自己只用 `bg-base` 的渐变，所以之前看起来没变化）和 `--dsw-specific-input-major`（消息输入框）。现在这两项跟 `bg-layer-1..4` 走同一档 alpha，弹层与菜单单独用更高 alpha 保可读。

**② 画面循环 `loop` / `loopSeconds`**：有些作品播一次就停（基于 `iTime` 的有限动画），新增「循环播放」开关 + 周期滑块（5–120s）。播放器在 `state.time += dt*speed` 后到点取模归零，只重置画面时间轴；声音走自己的实时时间轴，所以提示里建议带音乐作品别开循环。

**③ 音乐只播一次 `audioMode=once` + `audioSeconds`**：马里奥这类「静态图 + 一首歌」的作品，需要「音乐放一次、画面常驻」。实现：

- 播放器音频调度每 tick 检查 `audio.time >= audioSeconds` → `stopAudioScheduler('once')` + `setAudioState('ended')`（面板显示「音乐已播完（只播一次），画面照常」）；
- `startAudioScheduler()` 也加了同样的守卫，避免 `visibilitychange` / 「开声音」把播完的音乐又拉起来；
- 参数改动时（loop ↔ once）立即重新判断，不用切背景；
- 画面渲染完全不受影响（audio-smoke 断言：`state === ended` 后 chunks 不再增长，而 `frames` 继续涨）。

**④ 设置页配色**：原来的青绿色 accent（亮 `#0b8a80` / 暗 `#8fe9e4`）换成 DSH 品牌蓝 —— 亮色 `#3568dc`（比原生 `#4176e6` 深一档，保证 11px 数值也满足对比度）、暗色 `#7aaaff`（`--dsw-static-deepseek-400` 同色），`accent-soft` 同步换成蓝色低透明度。

**⑤ 代码框高度可调**：两个 textarea 去掉 `max-height` 限制、保留 `resize: vertical`，拖右下角即可调整；高度写进 `localStorage('shadertoy-skin.codeHeights')`，下次打开沿用。独立预览页补 `body.standalone { overflow: auto }`，否则行数一多超出一屏就点不到下面的控件（这也是 renderer-smoke 里那次 `#view-params intercepts pointer events` 的真因）。

**⑥ 整页设置不能滚动**：`body.mode-main { height:100%; overflow:auto }` 单独用不成立 —— `body` 的百分比高度要相对 `html` 的**确定高度**才能解析，而 `html` 是 auto，于是 body 跟内容一起长高、`html { overflow:hidden }` 又把视口滚动封死，底部的「音量 / 静音 / 恢复默认」就永远在视野外。修法：模式下给 `html` 也加 `mode-main` / `standalone` 类并设 `height:100%`，由 `body` 做固定高度的滚动容器（`overflow-y:auto`）。renderer-smoke 增加三条断言：`overflow-y=auto`、内容高于视口、`scrollTop` 真的能变。

### 9.10 下一步（M3）

多 pass（Buffer A–D + ping-pong）、音频可视化回馈（`iChannel0` 512×2：row0 FFT / row1 波形）、导入静态体检（外部纹理 / cubemap / 键盘 / `mainVR`）、自适应分辨率与电池降档。

### 9.11 用户海面（Seascape）背景：红块 bug、可移植优化与「插件到底慢不慢」的实测（2026-10-26）

**现象**：用户截图里海面出现大片亮红色斑块（他自己量：截图中 10.4% 像素偏红），并问「是不是插件导致的性能比较差」。

**① 红块根因（不是插件，也不收录作品代码）**：导入的 Seascape（© TDM，CC BY-NC-SA 3.0）在 post 里做 `pow(color, vec3(0.65))`，而 `color.r` 会变成负数 —— 唯一负项是水色 tint 项 `SEA_WATER_COLOR * (p.y - SEA_HEIGHT) * 0.18 * atten`（`p.y < 0.6` 时为负，最深约 −0.043），近场 fresnel≈0 时 `refracted.r ≤ 0.058` 压不过它。GLSL 的 `pow(负底数, y)` 未定义 → NaN。RGB8 转换在不同驱动上表现不同：**Intel Arc / ANGLE-D3D11 上 NaN 写进 R 通道得 255、G/B 保持有效值 → (255,50,84) 的 hot pink**；同一帧用 RGB32F 回读验证：NaN 像素集合与 `color.r<0` 集合逐像素完全相等（t=0/2/4 = 103,030 / 260,527 / 153,484 px）；g/b 从不小于 0，非 NaN 的有限负值不会变粉。相机/时间相关：shader 时间 t≈0→9.9%、t≈2→25.1%、t≈4→14.8%、t≈9→≈0%；用户的 `speed=0.05` 下约实时 40–160 s 后进入 10–25% 区间，所以是「过了一会儿才怪」。

**② 修法（不改摄像机与海面参数）**：
- post 先 `max(color, 0.0)` 再 pow（NaN→0，实测与「只修 NaN」基准逐像素一致，±1 LSB，零成本）；
- 时间轴去掉 `iMouse.x*0.01`：播放器只在拖拽时送 iMouse，原式让一次拖拽瞬移 ≈13 shader 秒 / 相机 z 64 世界单位（实测原版 iMouse=0↔100 时 SSIM 0.246）；
- 天空精确早退：`dir.y >= 0` 时混合权重恒为 0，直接返回 `getSkyColor(dir)`；
- 追踪改为有界 regula-falsi（海面高度 h≤HMAX ⇒ `p.y=-0.05` 处 map() 必为负，是真括号），32→16 步；同时去掉「`hx>0` 就当作 1000 单位外命中」的远平面早退（那是数学上的假命中，落在混合带里；去掉后画面无可测回归，也没有可测的硬边改善——别写成「修好了地平线」）；
- 每层第一个八度的 `choppy==4` 用两次平方代替 pow；post 加 ±0.5/255 interleaved-gradient 抖动（天空带化略减，640×405 下无颗粒）。
- 诚实边界：`specular` 底数 clamp 是 **no-op**（白点来自 spec×nrm>1，不是底数>1，实测爆点数量 2135 不变）；那些纯白小点是原作者的太阳高光，属于画面本身，别当 bug 修。

**③ 性能（Intel Arc iGPU / ANGLE-D3D11，交错 A/B + 1×1 readPixels 屏障；`gl.finish()` 在这条路径上不阻塞）**：1280×810 5.7→5.0 ms（1.13–1.16×，A/A 噪声 0.5–3%），640×405 1.64→1.41 ms（1.16×），用户 live 画布 1083×574 约 4.5→3.9 ms（30 fps 预算的 13.5%→11.7%）。**2× 在同一片海下做不到**：探针拆解 trace 56% + 法线 42% + 着色 <1%，两者都是画面本体；唯一「理论无损」的解析法线做到了 1.69×（梯度用有限差分校验 relerr 0.000），但参考实现的正则法线被 `eps=dist²·EPSILON_NRM` 隐式低通了，解析法线把高频法线还给场面，被 `pow(specular, 75–139)` 放大成密集白色闪烁（temporal 抖动 8.16%→14.61%），因此否决。要 2× 只能接受可见画质变化（法线 3 八度 SSIM 0.73 / 几何 2 八度 SSIM 0.53，约 1.8–2.2×）。

**④ 「是不是插件导致性能差」——不是**。同机实测（Playwright/Edge 真机）：插件播放器的 JS 每帧 p50 0.00 / p95 0.1 ms（只做 16 个 uniform + 4 次纹理绑定 + drawArrays），rAF 以 120 Hz 跑、30 fps 上限精确生效（30.0 fps / 33.3 ms 间隔）；`powerPreference:'low-power'` 与 `'high-performance'` 在 1084×574 上 4.48 vs 5.01 ms（噪声内，且 renderer 不变）；背景层不占 UI 线程。**全部 GPU 预算都在 shader 上**。用户观感「怪怪的」主要来自**渲染分辨率**而不是帧率：`scale=0.5`（1083×574 拉到 2166×1148）叠加 CSS `blur(1px)` 后高频损失约 88%（PSNR 26.7 dB）；实测 `scale=0.75 + blur=0` 明显更锐（成本约 8.7 ms/帧，30 fps 的 26%），`scale=1` 约 15.5 ms/帧（46%）。

**⑤ 资产与复现**：优化后的作品代码**不进包、不进 git**（CC BY-NC-SA 与仓库 MIT 冲突），存放在 `$DSH_HOME/shader-skin/presets/seascape-opt.glsl` 并写入 live 状态条目 `user-seascape`；改动前状态备份在 `$DSH_HOME/shader-skin/backups/state-pre-opt-*.json`。调查用的 GPU bench/对比/审计工具与报告在 `dsh-shadertoy/.tmp-seascape/`（gitignored，含 lab / compare / horizon / analyze、诊断报告、优化变体与两份独立验证报告），需要复现时直接跑那里的脚本。

**通用教训**：导入第三方 ShaderToy 作品时，「post 里对可能为负的颜色做 `pow`」是通病（原作者在别的驱动上看到的是黑点，在这里是洋红/红块）。以后代码页/导入路径可以在编译前做一条静态提示：输出前对 `pow` 的底数 `max(..., 0.0)`，以及注意 `iMouse` 在壁纸场景里不该驱动时间轴。

### 9.12 用户三连报 bug：亮色死白卡片、代码框拖不动、循环播放（2026-10-26 深夜）

**① 亮色下「有的 AI 回复整块纯白」**。`panels` 之前只覆盖 `--dsw-alias-bg-layer-1..4` / `bg-module-platform` / `specific-input-major` / overlay / menu，但 DSH 里有一批**内容填充直接读静态中性色**：改动文件卡头 `--changes-fill: var(--dsw-static-neutral-50)`（暗色换 `-850`）、交付物 / 计划卡（`--deliverable-fill` / `--plan-card-fill` / `--card-fill`）同理、markdown 代码块 `--dsw-alias-markdown-code-block`（亮 = bluish-50，暗 = bluish-900）、行内代码 `--dsw-alias-markdown-inline-code`、用户气泡 `--dsw-specific-bubble`（亮 = deepseek-50）。亮色主题下它们是不透明近白，于是「别的卡片都透、这几块死白」。修法：`client.js` 新增 `CONTENT_TOKENS`（token + 权重），只在 `panels = half/clear` 时给 `alpha * weight` 的透明值；静态中性色只覆盖 `-50/-100/-800/-850`（取证：把 `app.asar` 按 latin1 读成字符串，统计每个 token 的前一个 CSS 属性，确认这批只当背景/填充；`-00` 是白色文字/图标，不能动）。

**② 代码框拖不动**。旧实现靠 textarea 原生 `resize: vertical`，可 `::-webkit-resizer { background: transparent }` 把唯一的手柄涂成了透明 —— 用户看不到，Electron 里那 15px 的角落命中区也很难抓。改成 `resize: none` + 每个框下面一条可见把手（`div.code-grip`，`cursor: ns-resize`，`::before/::after` 两条小横线），`pointerdown` 捕获 + `pointermove` 改高度（Image ≥160px、Sound ≥80px，上限 72% 视口高），`pointerup` 写回 `localStorage`，把手指到把手上按 ↑/↓（Shift 加速）也能调。renderer-smoke 断言：把手存在 2 个、原生 resize 已关、拖动后高度 +100 以上、高度落进 localStorage、键盘能调。

**③ 「循环播放」＝两层问题**：

- **画面循环本身是好的**，只是文案没说清。dev 探针（`iTime > 5` 才变白的 shader）：`loop=5` 下 6.5s 仍全黑、`loop=off` 下 6.5s 变白 → `iTime` 取模确实发生。用户看到的是马里奥 shader 自带的 `col *= smoothstep(0.0, 2.0, iTime)`：每轮归零都从黑淡入，看着像「没循环 / 闪黑」。开关改名为「画面循环」（别再和音乐的「循环播放」同名），面板与 README 写清楚这是作品自身效果。
- **音乐「循环播放（一直放）」才是真 bug**：ShaderToy 的 sound pass 是有限长度的曲子（马里奥 55–60s 淡出），旧实现只是不停喂 `t = 60,61,…`，所以「一直放」实际是「放完就静音」。现在 `audioMode=loop` 按 `audioSeconds` 把音频时钟取模，接缝前后各 40ms 淡入淡出（`seamGain()` 逐采样，峰值/有效值按淡入淡出后统计），`once` 停止前同样 40ms 淡出；`once → loop` 切换时若已越过结尾就从 0 重放；「音乐时长」行改成「有声就显示」（两种模式都用它）；诊断行加 `music=loop/60s`。audio-smoke 新增 `dev/decay-sound`（1 秒后衰减到 0 的有限曲子）在 `loop + audioSeconds=2` 下：音频时钟必须出现回绕、状态保持 `running`、回绕后重新有声。

**通用教训**：① DSH 的「表面」不只有 alias `bg-layer` 一族，静态中性色也是一层皮，改透明度要按属性取证、别一把梭；② 别把「用户能不能看见/抓到」交给浏览器原生 chrome（transparent resizer、透明滚动条）——Electron iframe 里要真机拖一遍；③ 同名开关必须拆开（画面循环 vs 音乐循环），不然用户的描述会指向错的那一个。

### 9.13 分辨率下拉改成「看得懂的像素数」+ 更多档位（2026-10-26）

**问题**：「渲染分辨率」只有 0.5× / 0.75× / 1× / 1.25× / 1.5× 这种倍率，用户不知道实际渲染多少像素，也不知道该选哪个；档位也偏少。

**改法**：

- `scale` 档位扩到 11 档：0.25 / 0.35 / 0.4 / 0.5 / 0.6 / 0.75 / 1 / 1.25 / 1.5 / 1.75 / 2（`defaults.json` 的 `limits.scale.values`，播放器 clamp 同步放宽到 0.25–2）。最低档 0.25× 是 1/16 像素量，弱显卡/省电场景用；2× 标「最吃显卡」。
- 下拉每一项直接写**实际绘制缓冲**：`1280 × 810（1×）`、`512 × 324（0.4×）`；顶部 output 也改成像素数，下面一行提示写「实际渲染缓冲 … （窗口 W × H，DPR 上限 1.5）」。
- **坑**：设置页是主区域的 iframe，它自己的 `window.innerWidth` 只有主栏宽度，不是播放器（铺满整个窗口的 iframe）的宽度。所以尺寸要从 `parent.innerWidth/innerHeight/devicePixelRatio` 取（同源可读，跨域时 catch 回落到自身窗口），DPR 与播放器一样 cap 在 1.5。
- 窗口尺寸变化时（`resize`）重建下拉选项，否则标签会停留在旧分辨率。
- 播放器 `resize()` 给每边加了 8192 的安全上限：2× 叠加大窗口/高 DPR 会要 8k 级缓冲，宁可截断也别让 WebGL 上下文炸掉。
- renderer-smoke 断言：11 个选项、`1024 × 640（1×）`/`256 × 160（0.25× · 最省电）`/`512 × 320（0.5×）`/`2048 × 1280（2× · 最吃显卡）` 都存在、顶部与提示文字、选 0.25× / 0.5× 后数字变化、改视口后标签重建。

**教训**：给用户看的数值要用他实际能感知的量（像素），倍率只当括号里的注脚；iframe 里算「窗口尺寸」必须问 parent，不能信自己的 innerWidth。

### 9.14 README 演示视频改用裸链接；马里奥视频「看不了」的根因（0.2.2，2026-10-27）

**现象**：README 加上第二段演示视频后，用户反馈「马里奥那个视频看不了」。

**根因**（真机开仓库页 + 抓 DOM 确认）：README 里写的 `<video src="https://github.com/user-attachments/assets/…">` 会被 GitHub 渲染成一个「附件文件卡」（外面套 `<details>`，要展开才看到 video），里面 `src` **仍是直连的 user-attachments 地址**。这个直连在本机实测只有 **~13 KB/s**（2.758 MB 下完要 3 分半），页面里就一直停在 `readyState=0`；而拖进编辑器产生的**裸 URL** 会被 GitHub 换成 `private-user-images.githubusercontent.com/…?jwt=…` 的签名地址 + 它自己的播放器，秒开、可拖进度条。

**修法**：

- README 两段视频都改成「裸 URL 单独一行 + 下面一行斜体说明」，不再包 `<video>`；
- 删掉已下掉的 Seascape 截图 `docs/verify/readme-seascape.jpg`（README 引用同步删除），截图区只剩「马里奥」「代码页」两张；
- `docs/PUBLISHING.md` 第五节按这个结论重写（原来写的 `<video>` 包法正是这次踩的坑）。

**验证**：真机打开仓库页，两段视频都变成 `<video src="https://private-user-images.githubusercontent.com/…">`，`readyState=4`、时长 62.59s（马里奥）/21.87s（Seascape 修改版）；匿名 `curl` 两个 user-attachments 地址都 302→200 `video/mp4`。

**发版**：0.2.2 打包了这几轮的全部内容（分辨率菜单 0.25–2×、代码框可见把手、音乐循环重放、亮色内容填充、README 媒体整理）。

### 9.15 把两个第三方作品收进插件并声明各自的许可证（0.2.3，2026-10-27）

**决定**：上游 ShaderToy 作品默认 CC BY-NC-SA 3.0，允许再分发（署名 + 非商业 + 相同方式共享）。用户确认后，把**自己改过的 Seascape** 和 **马里奥**直接做成内置预设，并去掉自写预设名里的「（自写）」，自写的只标 MIT。

**落地**：

- `native-dist/presets/seascape.glsl`（桌面背景修改版：近地轨道机位 + 等价优化 + NaN 粉块修复，文件头保留 TDM 署名、修改要点、CC 声明）、`mario.glsl` + `mario-sound.glsl`（iq 的像素画 + 那首曲子）；
- `presets/index.json` 每个条目新增 `license`（`MIT` / `CC BY-NC-SA 3.0`）；第三方条目另带 `licenseUrl`、`author`、`sourceUrl`；自写三项名字去掉「（自写）」；
- 设置页：背景库行与预设下拉里第三方作品带红色 `CC BY-NC-SA` 标（`title` 写明「第三方作品：署名 / 非商业 / 相同方式共享」），代码页对第三方内置作品提示「另存的副本同样受该协议约束」；
- `THIRD-PARTY-NOTICES.md`：作品 / 作者 / 来源 / 改动一览 + CC 三条义务（署名、非商业、相同方式共享）+ 「商用请先删除这三个文件」；
- README「预设与许可证」改成表格 + 明确「npm 包整体 MIT，两个预设文件按各自 CC 协议分发」；
- `tools/check-bundle.mjs`：预设许可证白名单从 `MIT` 放宽为 `MIT | CC BY-NC-SA 3.0`；对 CC 预设强制要求 `author` / `licenseUrl`（必须是 creativecommons by-nc-sa 3.0 链接）/ `sourceUrl`，并检查**文件头真的含 `Attribution-NonCommercial-ShareAlike 3.0`**；原来「打包文件里不许出现 shadertoy view 链接」改成「只允许出现在 CC 预设文件里」——这条既保留了防误打包的意图，又给署名链接开了口子；
- renderer-smoke：背景库 5 项、两个 `CC BY-NC-SA` 徽标、预设下拉里出现许可证文字。

**许可证边界**：仓库/ npm 包整体仍以 MIT 为主，但 `seascape.glsl` / `mario.glsl` / `mario-sound.glsl` 不是 MIT —— 商用场景要先把这三个文件删掉；改过的版本再分发仍要留在 CC BY-NC-SA 3.0。

### 9.16 原生中性色、统一透明度、代码工作区与可靠性修复（0.3.0，2026-10-27）

**决定**：三条实验分支（`codex/native-ui`、`codex/code-editor`、`codex/core-fixes`）分别开发，合入 `codex/experiment-native-ui` 后再并回 `main`。设置页不再用品牌蓝，改用 DSH 自己的中性色；透明度收敛为「一套语义表面规则」，透明档不再保留任何最低底色。

**为什么换掉品牌蓝**：读取本机 DSH 安装包的主题实现后发现，原生界面用的是浅色白底 / 深色 `#151517` / 卡片 `#232324` / 字段 `#1b1b1c`。插件自己另起一套蓝色，和原生界面放在一起总像两个产品；换成中性色后是「同一套界面」，且深浅主题自动跟随。

**为什么不再覆盖静态色板**：上一版为了让亮色卡片有底，改了 `--dsw-static-*`。审查发现这套静态色板同时被原生**前景文字和图标**使用，全局改写会把文字一起变透明。现在只改语义背景 token（`--dsw-alias-*`），静态色板一律不动——`test:audit` 里有一条断言专门守着这条线。

**落地**：

- 设置页：按「背景与外观 / 渲染与性能 / 画面播放 / 声音」分组，宽窗双栏、窄窗单栏；删除页头英文小标、长说明与重复数值；自动保存提示改成浮层，不再把控件顶来顶去；新增「预览背景」（Esc 返回，不新增第二个渲染器）；页签与下拉支持键盘；三个页签共用同一处状态提示。
- 代码工作区：整行拖动条（上限 4000 px、贴边自动滚动、双击还原、方向键/Shift/Home/End 微调）、行号、12–20 px 字号、自动换行、单独收起、专注编辑（保留阅读位置、Esc 返回）；高度与阅读偏好持久化，未保存草稿在会话内用 sessionStorage 恢复。
- 透明度：`opaque` 原生底色 / `half` = `glass / 100` / `clear` = alpha 0。覆盖外壳遮罩（只合成一次）、新会话按钮、聊天输入框、Markdown 代码块（外框只画一次，顶部栏与正文不叠加）、行内代码、消息气泡、菜单、选择器、对话框，以及插件自身设置页、背景库与专注编辑。
- 可靠性（详见 [`core-review-2026-10-27.md`](core-review-2026-10-27.md)、[`full-audit-2026-10-27.md`](full-audit-2026-10-27.md)）：初始化计数按作品重置 + 请求序号丢弃旧响应；Host 串行原子替换、每次独立临时文件；状态 GET/PUT 加 ETag / If-Match（旧修订 409）；保存失败回退选择并保留草稿；JSON 显式取 Image、Common 合并进 Image 与 Sound、拒绝 Buffer/Cubemap/纹理依赖；编译失败保留旧 program 继续画；GPU 上下文丢失后重载播放器；本地预设符号链接解析真实路径后二次检查；画面速度只影响画面；音频尾段等播完再停；切换作品先应用音量再启动声音；导入按 UTF-8 字节与序列化后的请求双重预检。
- 测试：新增 `test:panel`（真实 client + 面板 + 播放器 + 磁盘持久化）、`test:ui`（中性色、冗余文案、键盘、预览、专注、窄屏）、`test:audit`（六种主题/透明度组合、GPU tint、草稿恢复、导入、多窗口 409、读取失败不覆盖、模拟 GPU 上下文丢失）、`test:surfaces`（设置页自身透明度、iframe 合成像素）、`test:transparency`（18 组语义表面组合）；CI 跑前三项，并把全部工具纳入 `node --check`。本轮顺手修了 `test:audit` 的一个启动竞态（iframe 已存在但 panel 文档还没解析完）。

**发版**：0.3.0 把实验分支的全部内容并回 `main` 并发布（`npm run check` 109 项、`test:host` / `test:renderer` / `test:audio` / `test:panel` / `test:ui` / `test:audit` / `test:surfaces` / `test:transparency` 全绿）。多 pass、纹理输入与键盘输入仍未实现，导入时会明确拒绝并提示。

### 9.17 README 演示视频换成两段新录屏（0.3.1，2026-10-27）

**决定**：顶部两段旧演示（62.6 s 马里奥 / 21.9 s Seascape）与两张预览截图全部撤掉，换成本次重录的两段：马里奥 61.2 s（设置页 → 卡片透明档 → 代码页 → 聊天，带音乐）、Seascape 19.0 s（近地轨道机位，纯画面）。马里奥左下角的头像 / 昵称用 16 px 马赛克盖住，Seascape 不需要处理。

**打码方式**（可复现）——只糊那一块，不模糊整帧：

```sh
ffmpeg -i 源.mp4 -filter_complex "[0:v]scale=1280:810:flags=lanczos,setsar=1,split=2[bg][fg];[fg]crop=96:48:6:760,scale=6:3:flags=area,scale=96:48:flags=neighbor[m];[bg][m]overlay=6:760,format=yuv420p[v]" -map "[v]" -map 0:a:0 -c:v libx264 -crf 28 -preset slow -c:a aac -b:a 128k -movflags +faststart 输出.mp4
```

**先缩到 1280 再打码**：块才是屏幕上的真像素块。在 2880 宽的原始帧上打完再缩，块会被 lanczos 糊成一片灰雾，看不出是马赛克。Seascape 源录音是纯静音（−91 dB），直接 `-an` 去掉音轨。

**验证**：1 fps 逐秒抽查整段视频左下角，马赛克始终在；侧栏在 42.8 s 收起，属瞬间消失，没有漏出未打码的头像。上传后的两个附件都匿名下载回来核对过：61.23 s / 1280×810（带 AAC 音轨）、19.03 s / 1280×820（无音轨），与本地编码一致。注意 `user-attachments` 的顺序与实际拖入顺序无关——按体积和时长认领：`9697…` 是马里奥，`a3f4…` 是 Seascape。

**发版**：0.3.1 只动 README 与文档（无代码改动，CI 仍跑全量；npm 上的 README 随版本更新）。随后用户确认连正文「改代码」一节里的代码页截图也一并撤掉——README 现在**没有任何图片**，只剩两段视频；这次按用户要求**不发版**，只推 `main`（npm 上 0.3.1 的 README 保持带那张截图的样子）。

### 9.18 全面代码审查与 CI 重构（audit，2026-10-29）

**范围**：Host half（`index.js`）、client half（`client.js`）、渲染器（`player-controller.js` / `player-runtime.js` / `pipeline.js` / `project.js` / `textures.js` / `render-worker.js`）、设置页（`panel.html`）、工具链（`tools/`）、CI/CD、README 与文档。完整清单见 [`audit-2026-10-29.md`](audit-2026-10-29.md)，这里只记结论与取舍。

**这次修掉的确定问题**：

1. **`npm run check` 在 npm 12 上直接失败**：`npm pack --dry-run --json` 从数组改成「以包名为键的对象」，`check-bundle` 只认数组。现在两种结构都接受，并加了 parser 自检；同时补了 README / LICENSE / `assets/`、`screenshots.json` 的打包断言。
2. **`test:multi` 偶发超时（CI 曾在一条 docs-only 提交上变红）**：面板状态同步与测试注入的 `init` 竞争，控制器的 100 ms 去抖会把已排队的 preset 顶掉。改成「注入后 3 s 内没生效就重发」（最多 10 次），失败时报明确原因。
3. **音频设备异常会杀掉整个背景**：`player-controller.js` 的 `stop()` 被用在音频路径上。现在只拆音频链路、把错误作为 `audio` 状态上报，渲染继续；`test:worker` 增加用坏 `AudioContext` 的回归。
4. **`iChannelTime` 语义错误**：font / noise 等纹理通道返回了当前帧时间（ShaderToy 语义是 0）。`pipeline.channels()` 现在对纹理给 0，只有 buffer 给自己的 pass 时间；`test:multi` 用「时间必须为 0」的 shader 断言。
5. **键盘纹理每帧整块上传**：清空「本帧按下」行时无条件 `keyboardDirty = true`，等于每帧 3 KB `texSubImage2D`；改成只有确实按下过才上传。
6. **`resize()` 异常外抛**：帧缓冲分配失败会把异常抛进消息处理器和 rAF 循环；现在捕获、保留上一次可用尺寸并只报告一次。
7. **设置页在大型背景库下卡顿**：拖滑块的每个 `input` 都把整份状态（最多 1.5 MB 代码）序列化进恢复日志，并重建背景下拉。恢复日志改为只在 320 ms 防抖后的真实保存里写；下拉只在选项/当前作品变化时重建；代码页「未保存」改为 extra 文件 dirty 标记，行号只在行数变化时重建；粘贴/代码草稿改为 300 ms 防抖。
8. **设置页细节**：重复的「音乐时长」标签改为「时长（秒）」；窗口 resize 合并到每帧一次；主栏模式把 `role="dialog"` 改成 `role="region"`，用页头标题作 accessible name。
9. **Host**：entry id 长度上限 200（此前可存任意长字符串）。
10. **README 数量过期**：预设 11 → 12、第三方"八个" → "九个"。

**CI/CD 重构**：

- `ci.yml`：语法检查改为 `git ls-files '*.js' '*.mjs' '*.cjs'` 全量（手写清单漏过 `tools/inspect-live.mjs` 等）；浏览器套件从「一个 13 分钟串行 job」拆成 12 个并行 job，失败按套件命名，并把原先只在本地跑的 `surfaces`、`transparency` 纳入 CI。
- `publish.yml`：发布前先并行跑同一批 12 个套件（`verify` matrix），全部通过才进入 `publish`；tag/版本校验、OIDC 与 provenance 不变。
- `docs/PUBLISHING.md` 同步新的两段流水线。

### 9.19 TypeScript 7 只做类型检查，不做构建（2026-10-29）

**背景**：用户提出「如果明确适合 TS 重写带来提升可以做，放个 TypeScript 7.0.2」。评估后决定：**采用 TypeScript 7 作为纯类型检查器，不把源码改成 `.ts`、不引入构建步骤**。

**为什么不重写成 `.ts`**：

- 这个插件的卖点之一是「零构建、零运行时依赖」：npm 包直接发 `index.js` / `client.js` / `native-dist/*.js`，`native-dist` 由 Host 按请求从磁盘读、改完刷新即生效，测试也直接 import 这些源文件。
- 改成 `.ts` 要先编译产物、再决定打包与 sourcemap、再改发布流水线和「改文件即生效」的开发流程；对一个 0.x、用户要求稳定优先的插件，这不是明确收益。类型能提供的东西（函数契约、状态形状、JSON 解析边界）用 JSDoc + `checkJs` 同样拿得到。
- 浏览器专用适配层（`client.js`、`panel.html`、`player-controller/runtime`）依赖 Harness/Worker 自建 shim，需要手写 ambient 声明才可能通过检查，收益/成本比不高，因此不纳入检查范围（`tsconfig.json` 里写明了原因）。

**落地**：

- devDependencies：`typescript@7.0.2`（精确版本）、`@types/node@24`（host half 用）。
- `tsconfig.json`：`allowJs` + `checkJs` + `strict` + `noEmit`，target ES2022 / module NodeNext，lib 含 DOM（`TextEncoder`、画布类型），`types: ["node"]`；覆盖 `index.js`、`native-dist/project.js`、`pipeline.js`、`textures.js`。
- `npm run typecheck`（`tsc -p tsconfig.json`），接入 `npm test`、CI 独立 `typecheck` job、发布前的 `npm test`。
- 类型化时顺手修掉一个真实缺陷：`pipeline.resize()` 原来逐个 pass 删旧 target 再建新 target，中途帧缓冲分配失败会让 pass 没有 target，而 `width/height` 已经改了，之后每帧 `channels()` 都会抛异常。现在先整代分配、成功后一次性替换旧 target，失败时保留旧尺寸继续渲染。

**取舍**：JSDoc 类型写在源码里，函数签名本身就是文档；不新增 `.d.ts`、不改变 npm 包内容。以后代码规模明显变大或需要对外提供类型时，再考虑迁到 `.ts` + 构建。

### 9.20 音乐结束判定：图像不参与（2026-10-29）

**问题**：用户提出「音乐和图像一起结合判断会不会更好」。`audioDurationMode: auto` 目前只看音频：最后一次有声后连续 3 s 静音就锁定音乐时长；如果真实音乐中间有 ≥3 s 的间奏，会被提前截断。

**研究**（完整分析见 [`research/04-audio-image-end.md`](research/04-audio-image-end.md)）：

- **反例**：随包 `take-on-me` 音乐 180 s 结束、图像还有 29 s 动画。若要求「图像也结束」才认音乐结束，这类作品永远学不到音乐时长，`loop` 不再回绕、`once` 永不结束。`racing` 音画同长但检测有 500 ms 颗粒度，也不能保证图像先结束。
- **图像仍然在动时提高静音门槛**（3 s → 8 s）能减少间奏误判，但会让上面这类作品多播 5 s 静音才回绕，是 tradeoff 不是净改进。
- **更值得做的是音频包络置信度**：静音前是否有淡出趋势；高置信度 3 s 锁定，低置信度等 6 s。不依赖图像、没有反例，也不改变最终锁定的时长值。

**决定**：本轮不改默认行为（避免改变已有预设与导入作品的听感），把「图像辅助加速」和「音频包络置信度」记为后续可选项；若之后有「间奏被截断」的反馈，优先实现后者并用 `test:core` 的合成 shader 加回归。

### 9.21 商店截图改为手动维护，脚本只生成图标（2026-10-29）

**决定**：不再从演示视频里自动截帧做商店截图。视频录屏里有输入法浮动条、侧栏内容与压缩痕迹，构图也不可控；用户已手动截了更好看的图，后续换图也按手动方式。

**落地**：

- 删除 `tools/make-market-assets.cjs`（它同时管图标与视频截帧），缩成只渲染图标的 `tools/make-icon.cjs`（从 `icon.svg` 生成 `assets/icon-180.png`，列表只接受 png/jpg/webp）。
- `docs/market/` 保留现有截图，新规范写在 [`market/README.md`](market/README.md)：1280×740、文件名顺序即 `screenshots.json` 顺序、不要出现头像/昵称/输入法浮动条/本机路径、换图直接覆盖同名文件。
- `screenshots.json` 仍是仓库根的展示清单（dsh-market 读取），不随脚本生成。
- CI 的语法检查按 `git ls-files` 自动覆盖 `make-icon.cjs`，不需要再维护清单。

### 9.22 音画按「较晚结束」的一方联播（2026-10-29）

**背景**：用户提出，与其用图像参与「音乐是否结束」的判断，不如把作品结束定义为**音乐与画面两者中较晚的一方**。分析（§9.20）指出图像不能当音乐结束的前置条件，但用户这个提法暴露了另一个真实缺陷：画面与音乐原来**各自回绕**。`take-on-me` 画面 209 s、音乐 180 s，音乐每 180 s 重播一次，而画面还在结局段落里——两条时间轴越播越不同步。

**实现**：

- `jointLoopPeriod()`：两边结束点都已知时取 `max(画面, 音乐)`，供画面循环与音频循环共用；音频在音乐结束后继续输出静音，直到联播周期才回绕。
- 只有一方已知（持续动画 + 有限音乐，或反之）时保持各自独立，维持原行为。
- **只在 1× 速度启用**：`state.time` 是倍速缩放的画面时钟、音乐是实时时钟，其他速度下 `max()` 会对应不同的真实秒数，退回独立循环。
- `__player.playback` 新增 `imageDuration` / `loopPeriod` 便于诊断；`test:multi` 用两组显式时长断言联播周期，并断言 2× 下不启用。

**边界**：联播周期依赖时长正确性——显式 `duration` 最可靠；自动识别的误判只影响联播周期，不影响音乐锁定的时长值。