# 桌宠联动子包

本包只包含官方 pet 桥接、四条演出排播、调参面板、九段定制动画及五张配图。不包含 pet 渲染器、Electron、完整基础素材或第三方补丁安装器。

## 使用

1. 按仓库的完整源码部署步骤安装 Wallpaper 的主包和七个子包。
2. 自行安装并启用官方 [dsh-pet](https://github.com/PC2005-cloud/dsh-pet)，将目标设为网页显示。官方需提供同页 `petApi7340.pose/progress` 和 `/dsh-pet-7340/` 下的 config、lock、anim、position、throw 接口。审计基线为官方提交 `7440b963ab7fb962cb7694e094aa0c9c7a438a7b`；同为 `0.3.7` 的旧构建不一定有这些接口。
3. 将 Wallpaper 吉祥物设为官方侧栏模式，按 `Ctrl+Shift+D` 打开面板，刷新并选择目标 petId，再分别试跑四条逻辑。

没有官方 pet、服务缺失、目标隐藏或联动关闭时，只停用联动，吉祥物原生侧栏操作继续可用。不会自动安装、启用或修改官方 pet。目标缺失不会自动改控另一只宠物。

## 控制边界

- 宿主按 petId 协调页面，保管官方锁凭证并顺序下发白名单指令；短租约、失锁和旧响应清理不会强占新运行。
- 官方同一 pet 的动作会同步到其他显示端。`surface` 不是单页定向，本包不承诺跨端隔离。
- 发起页面自绘气泡并读取官方 pose 跟随。动作结束释放官方唯一锁后，气泡可以继续存在；不调用官方 broadcast 或 bubble/clear，也不注入桌面透明窗。
- 侧栏、抓绳、踢腿弹飞、哈气四条排播使用同页 playbackId 与实际视频进度触发节点。位置和抛掷交给官方 `position/throw`；不查询宠物 DOM、不改 React 私有字段、不逐帧发 HTTP。
- 官方直线位移按墙钟推进，不能保证视频缓冲时的逐帧贴边同步。旧私有运动面的精度不作为当前接口已实现的能力。

## 参数与验证

面板提供目标选择、四逻辑参数、运行、停止、重置和 JSON 导出。五张气泡各有出现与隐藏的动作、开始/结束锚点及毫秒偏移；重置当前逻辑同时清除该逻辑的气泡节点。参数是当前页运行时覆盖，刷新前请导出。

```sh
npm run build
npm run verify:pet-link
```

回归覆盖协议协调、真实本地 HTTP、素材 Range、独立气泡生命周期、四条排播、缺席回退和卸载竞态。`npm run verify:pet-link:integration` 检查真实 Cordis 配置更新与启停；`npm run verify:pet-link:browser` 检查独立浏览器中的自有气泡、配图加载及调参面板。浏览器夹具不等于官方完整 React 宠物或桌面窗口的视觉验收；不能把接口单测当成所有动画均已真机验收。

## 从旧版本迁移

内置 pet 和修改第三方文件的安装器已退役。旧 profile 里的派生依赖、bundle 选择、数据及曾经安装的外部补丁不会自动清除。关闭宿主后先停用旧内置 bundle，再更新 Wallpaper；外部补丁应通过其原备份恢复或重装官方包，不对活动安装做故障注入。

本包保留联动定制素材，不包含官方完整资源、字体及个人数据。代码许可证不替代素材授权；素材分发与商用范围须分别确认。本轮不发布 npm。