# 界面与动效设计基线

## 方向

以 DSH 原有界面为主体。控制面板是紧凑工具面板，使用系统字体、宿主明暗主题与清晰的表单层级。强调色优先沿用宿主语义 token，无该 token 时使用单一红酒色 OKLCH 回退；不用装饰卡片、整页背景或大面积渐变。

## 布局与语义

固定入口与醒酒控件永不参与动效，保持可点击。Alpha.8 面板宽 320 px，在窄窗口内限制为可用宽度；提供「界面律动」「飞行玩偶」两个独立复选框、微醺／上头／整活三档、「原梗 BGM」及开喝／暂停／醒酒。保留必要状态与错误反馈，不再呈现本地文件、BPM、相位、点击测速、分区域范围、玩偶尺寸／速度与总强度自定义控件。启动控制器时保留预设与三个开关，其余高级项恢复默认；底层校验与音频资源路径仍保留兼容用途。全部可操作控件有可读标签、键盘焦点与状态反馈。

## 独立开关与共享时钟

沿用 Alpha.7 的 `pageEnabled`／`petEnabled` 独立布尔设置，默认 `true`／`false`，插件本身仍默认静止。旧 `mode` 只用于兼容迁移：`pet` 映射界面关／玩偶开，`page` 映射界面开／玩偶关，明确布尔值优先。用户点击「开喝」后运行已勾选效果；运行中开关其中一者只挂载或清理该效果，另一者保留动画与时基。两个效果共享固定时钟、相位与幅度配置；固定 120 BPM，控制器恢复高级项默认：相位 0、强度 65、玩偶 180 px 与 180 px/s、全部区域开启、后台不播放、Escape、循环 true。暂停／恢复、醒酒和 Escape 走共同生命周期。

## 整页动效

Alpha.8 的适配器补充普通 `div`／`span` 文字、页头、侧栏文字及行内图片／SVG 等候选，避免仅依赖部分语义标签导致漏选。扩大识别后仍保留可见性、预算、父子单根、输入／选区／审批、滚动根及已有变换冲突保护；插件控制器与玩偶排除在扫描之外。覆盖统计包含直接动画和由祖先带动的区域，不把每个 DOM 节点都建立动画当作目标。

保留以 [参考动效观察](docs/MOTION-REFERENCE.md) 为方向的整页曲线：底部基本固定，整组对象同相位，大幅周期性压矮与拉高。每拍是一个平滑周期，不拆成起跳、落地和多次回弹；整页元素的 `translate` 与旋转均为零。纵向形变承担主要节奏，横向使用较小的反相补偿，避免整块等比例放大或过度横向撑开。保持档位不变时，每轮的时长、波形与幅度保持不变。

浏览器原生 WAAPI 按共享的 `document.timeline` 时基持续播放全部目标，不由 JavaScript 在每个 rAF 中手动写入 `currentTime`。新目标沿用既有时基；底层兼容 API 在 BPM／相位改变或源时钟发生大于 120 ms 的跳转／循环不连续时才重新对齐，小于该阈值的媒体校时不逐帧追赶。简洁面板固定 BPM／相位，Alpha.9 内置 BGM 不进入这一媒体时钟。不同类别仅改变幅度，使用同一相位。保护解除后排期在下一个中性拍界重新加入，等待期不覆盖宿主样式。父消息参与时，其内部正文和工具卡随父级形变，只保留一根自有 WAAPI 动画；父级不参与时，子区域才独立参与。覆盖统计应区分直接动画与父级带动，不能用独立 Animation 数替代实际可见区域覆盖。

采用以底部为中心的缩放；只有不与宿主已有变换冲突时才临时设置自有 `transform-origin`，退出时恢复。只动画合成属性，不改变字体、行高或盒模型。已有变换冲突、固定定位祖先及滚动根不直接叠加动画。

源码曲线以一拍相位 `p` 计算 `s = sin(2πp)`、`d = (stretch+squash)/2 × s + (stretch-squash)/2 × s²`，再按类别权重与用户强度缩放：`scaleY = 1 + 0.62 × weight × intensity/100 × d`，`scaleX = scaleY^-0.5`。微醺 stretch／squash 为 0.20／0.25，上头为 0.45／0.55，整活为 0.55／0.70；因此上头档为 `d = 0.50s - 0.05s²`。使用 33 个关键采样点和线性插值组成单一周期，0、0.5、1 周期为中性，0.25 最高、0.75 最矮。横向补偿小于倒数补偿，不再约束二维面积严格为 1，也不宣称三维体积守恒。

默认「上头」档、强度 65 时，消息根的纵向 scale 设计范围为 0.77835–1.18135；侧栏权重 0.65，纵向约为 0.85593–1.11788。这些是源码设计参数，不能代替实际画面验收。档位只改变形变幅度；性能保护的目标预算为 120／80／48／28，不改变幅度、曲线或速率，也不隔帧推进动画。控件悬停保护只跟随实际指针移动或按下更新，避免变形边界穿过静止指针时造成保护／恢复自激；焦点、IME、选区等保护仍单独生效。

## 飞行桌宠

沿用现有蓝白鲸鱼娘毛绒玩偶透明图：由本项目通过 imagegen 生成，随包为独立 PNG，经 DSH Host 同源固定静态路径加载，无外部素材 HTTP 请求；不宣称官方素材，不提供三维转身。桌宠独立挂载于 `shell.overlay`，标记为插件自有节点，避免整页扫描器对它叠加宿主目标动画。浮层点击穿透，固定入口与醒酒按钮保持可操作。

外层负责位置，按时间差与恒定像素速度推进，碰左右边界反转水平速度、碰上下边界反转垂直速度；只随机初始方向，不逐帧随机改速或改向。内层负责固定节拍的非等比形变，与外层移动解耦，碰撞不重置动画、相位或曲线。以最大形变包围范围约束边界，窗口缩小时校正位置。Alpha.8 固定默认尺寸 180 px、速度 180 px/s；底层兼容校验范围仍为尺寸 80–320 px、速度 40–600 px/s。运行范围是包含 DSH 侧栏的页面可视区，不跨到浏览器工具栏、其他应用或操作系统桌面。

## 可退出性

默认静止，用户手势开始播放。减少动态效果偏好优先；焦点、选区、IME、拖拽、审批触发整页相关区域保护，桌宠不变换宿主元素。暂停冻结两个效果的形变与桌宠位置，内置音乐同步暂停并保留进度；醒酒／Escape 走同一清理路径并将音乐归零。后台同步暂停，卸载释放媒体资源；折叠面板不改变播放状态，固定醒酒入口始终能停止声音。面板明确区分运行、暂停、保护、兼容未知与降级状态。

## 内置原梗音频

`musicEnabled` 默认 false。勾选并点击「开喝」后，使用 HTMLAudioElement 播放包内独立 MP3 的同源路径；音量固定 0.5、`loop=true`。音轨由用户指定的活跃黑江乐 `BV1hXbN6VEKV` 导出，设置与声明保留「音频：[BV1hXbN6VEKV](https://www.bilibili.com/video/BV1hXbN6VEKV/)」跳转链接。不创建视频、iframe、平台播放器或外部平台媒体请求。

Alpha.13 的 Host 仅通过标准 `webServer.register` 注册两个固定 exact 资源路径，读取随包的 `lib/assets`，不把请求参数拼为磁盘路径。支持 GET／HEAD、字节 Range、缓存重新验证和卸载清理。真实 ModuleLoader 入口保留完整业务代码，媒体不再转为 base64；构建入口与媒体产物加入 Git 并做可复现检查，满足按源码检查入口的市场需求。路径相对 Web 应用地址解析；Desktop／file 载体仍不在支持范围。

暂停和页面隐藏时 `pause()`，保留进度；恢复后继续原音频。醒酒／Escape 停止并回到开头；卸载清除媒体来源与监听器。异步 `play()` 的拒绝和启停竞态必须处理，失败显示可读错误。音乐与两个视觉效果的启停共用控制器生命周期，但音乐不作为视觉节拍源；界面和玩偶保留固定 120 BPM，不宣称与歌曲逐拍精确同步。来源、导出参数和独立的素材权利范围见 [素材说明](docs/ASSETS.md)。

## 视觉验收

至少检查明暗两套主题、窄窗口、键盘焦点、打开的面板和关闭面板状态；真实 DSH 与模拟宿主截图分别标注。检查 320 px 面板仅呈现精简操作、普通文字与图像新增覆盖、音频来源链接可见且可跳转、无左下角视频窗口。分别检查界面单开、玩偶单开、同时开启与全关，运行中开关任一者时另一者不重新起拍。桌宠连续飞行中需检查水平／垂直反射、窗口缩放、点击穿透和暂停恢复；碰墙前后固定 Q 弹曲线不变。BGM 无平台请求、正确内置音轨、循环与所有暂停／退出路径均需独立验证，不能以资源加载事件代替媒体进度及实际声音检查。

对照参考观察整页多个连续周期或录屏，确认底部稳定、整组同相位、循环的时长和幅度保持一致，性能保护切换不使保留目标变形变速，静止指针也不造成周期性断续。纵向形变明显且横向补偿较小，没有离地多次回跳、错相和父子叠加。对比运行与关闭状态，检查输入框、弹窗与滚动区域没有新的溢出或遮挡。单张截图不能证明节奏，也不能替代输入、IME、选择、复制与性能验收。