# 开发与测试

## 代码位置

- `src/frames.js`：轮播顺序，共 14 张。
- `src/playlist.js`：前后切换、计时、暂停和预加载。
- `src/background.js`、`src/background.css`：背景图层、淡入淡出、播放按钮和显示强度。
- `src/floating-controls.js`：播放条悬浮定位、输入框避让和观察器清理。
- `src/preferences.js`：浏览器本地偏好和旧版播放位置迁移。
- `src/settings.js`：DSH 通用设置里的间隔选项，使用宿主提供的 React。
- `src/client.js`、`src/index.js`：客户端和插件入口。

前后两层图片叠放，新图淡入时旧图保持在底下，避免过渡到一半时突然变暗。普通切换为两秒，减少动态效果模式下直接切图。皮肤不调用模型，也不请求远程图片。

## 构建

需要 Node.js 22.19 或更新版本。

```powershell
npm ci
npm test
npm run pack:release
```

普通构建使用已有 WebP，不修改图片。需要重做裁切时运行 `npm run assets:prepare`；该步骤保留原始 PNG。`lib/client.js` 内嵌图片和样式，安装包无需附带原视频、源素材或开发依赖。

修改并分发安装包时请递增版本号，避免 pnpm 复用同名、同版本的旧包缓存。0.3.5 让播放条按真实几何自适应：输入卡占住右下角时隐藏「尼可 · x/14」计数并收窄回角；收窄横条也放不下（窄窗/竖屏）时改竖排、仅悬在输入区上方 8px，保留暂停键，仍不遮发送按钮。0.3.4 让活跃会话里输入区外圈的底板透明、露出背景，卡片自身的表面保留。0.3.3 去掉了 0.3.2 的 52px 留白，恢复原生输入区位置。播放条悬浮时低于原生触发菜单和弹窗，与输入框可能重叠时只调整自身，不动宿主布局。窗口、输入框尺寸和会话节点变化触发重新定位，卸载时清理观察器和监听器，没有常驻轮询。0.3.6 让轮播在被停掉的计时器上自愈：窗口从后台、托盘或最小化回来时核对停留计时器，切换过程抛错时跳过该帧继续播放，不再卡死。0.3.7 适配 DSH 新版把对话区 slot 从 `conversation` 改名成 `main.conversation`、输入区外圈容器从 `[data-input-backdrop]` 改成 `[data-input-scroll]`：透明规则同时匹配新旧命名，测试 fixture 也用 `:is()` 兼容两种宿主；同时把挂载、设置项注册和清理包进故障隔离，出错只记日志、不冒泡进宿主。

## 真实 DSH 测试

需要本机 Chrome 和 pnpm，首次准备隔离环境。`.lab/runtime/package.json` 固定验证用的 DSH 版本（当前 `0.1.5-rc.1`）；改这一行再跑一次 `npm install --prefix .lab/runtime`，就能换一个宿主版本重跑整套验证。

```powershell
node scripts/setup-lab.mjs
npm install --prefix .lab/runtime
npm run pack:release
npm run verify:dsh
```

测试只使用项目内 `.lab/` 下的独立 DSH 配置和 `127.0.0.1:3091`，不使用日常 DSH 配置；请保持这个端口空闲。脚本会实际安装包、核对安装内容、运行浏览器测试、卸载插件并检查界面恢复。

单元测试有 37 项，安装后浏览器测试 18 项，卸载后测试 1 项。覆盖素材裁切、双向循环、五档计时、暂停、后台标签页、减少动态效果、偏好恢复、断网、浅深色和窄屏。

按钮遮挡回归测试在实际安装的 DSH 页面上模拟有消息的 `active` 布局和消息内容替换，移除欢迎页专用间距并保留宿主原有 CSS。使用普通鼠标点击验证前后切图及暂停功能，检查原生发送键不被覆盖、设置弹窗遮挡和关闭后的恢复；仅检查按钮“可见”不足以发现底板拦截点击。此项不调用模型，也不等同于真实发送消息或侧栏切换会话的端到端测试。

测试基线为 Windows、DSH 0.1.5-rc.1、Chrome（0.1.2-rc.1 上同样回归通过）。构建目标为 Chrome 111+、Firefox 121+、Safari 16.4+，不表示已逐一实测。没有配置真实模型进行长篇流式会话测试。

## 提交范围

根目录 `.gitignore` 只放行完整版的源码、测试、素材、必要文档和当前安装包。Lite、历史包、依赖缓存、视频、测试配置及登录资料不属于这个仓库的提交范围。新建顶层文件时，需要明确决定是否加入规则。

测试会生成本地 DSH 凭据；不要提交 `.lab/`、浏览器存储状态或失败测试的 trace。提交前检查文件列表，不要使用强制添加来绕过忽略规则。直接压缩整个工作目录或从网页拖入整个目录不会应用 `.gitignore`。