dsh-plugin-startup-animation 1.12.7 → 1.13.0

package/README.md

@@ -28,7 +28,7 @@
 `webServer.register` 提供素材与管理路由。**运行时不依赖任何 npm 包**，浏览器半边只从宿主的
 模块表 `require('react')`，装好即用、无需构建。
 
-开箱自带 **7 段视频 / 7 张壁纸 / 9 段语音**，也支持上传你自己的 MP4 / WebM / GIF /
+开箱自带 **8 段视频 / 7 张壁纸 / 9 段语音**，也支持上传你自己的 MP4 / WebM / GIF /
 PNG / JPG / MP3。素材在设置页里点卡片即用，展示时长可以在 **3–30 秒**之间调；声音有两个
 彼此独立的开关——视频自己的音轨，以及单独的开机音频。
 
@@ -48,7 +48,7 @@ PNG / JPG / MP3。素材在设置页里点卡片即用，展示时长可以在 *
 
 **视频素材库** —— 卡片点选即用，来源直接标在卡片上（内置 / 上传），当前在用的那张标「使用中」：
 
-<img src="docs/library.jpg" width="520" height="261" alt="视频素材库">
+<img src="docs/library-videos.jpg" width="520" height="262" alt="视频素材库">
 
 **壁纸素材库** —— 同样点卡片即生效，来源标记同上：
 
@@ -132,7 +132,7 @@ dsh plugin --profile <你的 profile> add /该仓库的绝对路径
 | 开机音频 | 动画期间另播一段音频文件。 |
 | 展示时长 | 3–30 秒，视频与壁纸共用。**跳过不受它限制**。 |
 | 启动画面素材 | 当前素材预览，以及「恢复默认」（回到内置动画）。 |
-| MP4 / 壁纸 / 音频 / 更新公告 四个页签 | 前三个是素材分类：点卡片即选用、上传即入库。**更新公告**是只读页，显示最新版 Release 的更新说明。 |
+| MP4 / 壁纸 / 音频 / 宠物 / 更新公告 五个页签 | 前三个是素材分类：点卡片即选用、上传即入库。**宠物**是桌面宠物的开关、大小与动作预览。**更新公告**是只读页，显示最新版 Release 的更新说明。 |
 | 卸载 / 更新 | 装在当前 profile 里时显示。**卸载插件**会把它移除（设置与上传素材保留在磁盘）；有新版时版本号变成一个更新按钮。两者都要重启 DSH 才生效。从源码目录 `link:` 进来的安装不给更新按钮——那条依赖不指向任何版本。 |
 
 没选素材时，插件会播放**自己的内置动画**（配色随应用深浅色走的旋转徽标）。
@@ -169,6 +169,23 @@ dsh plugin --profile <你的 profile> add https://github.com/WWFZS/dsh-plugin-st
 你的配置（`$DSH_HOME/startup-animation.json`）和上传素材
 （`$DSH_HOME/startup-animation-media/`）都在包**外面**，升级不会动它们。
 
+### 桌面宠物
+
+设置页的 **宠物** 页签会让一只透明小动物浮在界面右下角（不影响任何操作，它就是浮在
+页面上的一层）。
+
+- **动作轮播**：按动作列表从第一个到最后一个依次演（待机、点击回应、害羞捂脸、
+  拖拽悬空、原地踏步、吃橘子、挥手打招呼、原地小憩、泡温泉），每个动作演完一遍
+  **定格 3 秒**再演下一个，到表尾绕回开头；加新动作会自动排进轮播
+- **右键菜单**：列出所有动作供你点播（演哪个点哪个，演完从它的下一个继续轮播）、
+  归位、隐藏
+- **左键点一下**：插播「点击回应」，播完继续轮播
+- **拖动**换位置（拎起来会演「拖拽悬空」），松手记住位置、继续轮播
+- **大小** 100–320 px
+- **动作列表**在设置页里：点一格就点播那个动作，正在演的会高亮；
+  **加动作只要往目录丢文件**（文件名就是动作名，不用改代码、不用重启，刷新页面即见）
+- 素材已经去掉绿幕和脚下的地面投影，所以它是**悬浮**在界面上的
+
 ### 配置文件
 
 配置存在 `$DSH_HOME/startup-animation.json`（一般是 `~/.dsh/startup-animation.json`），
@@ -204,10 +221,13 @@ dsh plugin --profile <你的 profile> add https://github.com/WWFZS/dsh-plugin-st
 
 以下全部随包分发，在列表里直接可选：
 
-- **MP4** —— 7 段，全部为 H.264 faststart（可直接流式播放，每段 1.6–6.2 MB）。
-  `dsh-大肥鱼`、`剑一`、`薰衣草花语-等你爱我` 带语音音轨（打开「视频带声播放」即可听到），另外四段无音轨
+- **MP4** —— 8 段，全部为 H.264 faststart（可直接流式播放，每段 1.6–6.2 MB）。
+  `dsh-大肥鱼`、`剑一`、`薰衣草花语-等你爱我`、`少司缘` 带语音音轨（打开「视频带声播放」即可听到），另外四段无音轨
 - **壁纸** —— 7 张，附带预生成的 480px 缩略图供列表使用
 - **音频** —— 9 段语音
+- **宠物** —— 9 段透明动画（待机 / 点击回应 / 害羞捂脸 / 拖拽悬空 / 原地踏步 /
+  吃橘子 / 挥手打招呼 / 原地小憩 / 泡温泉，VP9-alpha webm）。
+  它们**不进**素材列表，只由宠物浮层取用。
 
 > 所有素材均来自网络，感谢各位 UP 主的优秀作品。仅作演示用途，版权归原作者所有；
 > 商业再分发前请先看 [ASSETS.md](ASSETS.md) 确认每个文件的来源。

package/client.js

@@ -3,9 +3,13 @@
  *
  * **一个** settings.section 条目（侧栏只显示「启动动画」），页面自上而下：
  *   1. 设置区（常驻）：总开关、声音、展示时长（共用主配置，3–30 秒）、当前素材预览 + 恢复默认；
- *   2. 分类切换器 [MP4 | 壁纸 | 音频 | 更新公告]；
+ *   2. 分类切换器 [MP4 | 壁纸 | 音频 | 宠物 | 更新公告]；
  *   3. 分类区：上传（按文件类型自动归入本分类）+ 该分类素材**卡片网格**（点卡片即用，悬停出删除）。
  *      「更新公告」不是素材分类：它渲染 `/update` 顺手带回的 Release 正文（parseReleaseNotes）。
+ *      「宠物」也不是素材分类：它是宠物开关 / 大小 / 动作预览，真身是页面右下角那只浮层。
+ *
+ * 宠物浮层（createPetOverlay）在 apply 阶段挂到 document.body 上，与设置页渲染树无关：
+ * 关掉设置页它也还在，靠 window 事件（dsa:pet-sync / -play / -reset）和设置页通信。
  *
  * 素材**只在** MP4 / 壁纸卡片里选用：上传只入库不生效，点卡片才写入配置。
  * 删除语义：内置素材 = 从列表隐藏（包内文件保留）；上传素材 = 真删文件。
@@ -84,6 +88,19 @@ window.__ModuleLoader__.load({
       updateChecking: '检查更新中…',
       updateLatest: '已是最新',
       updateUnknown: '检查不到更新',
+      // ── 宠物（第三个页签；浮层与设置区的文案）──
+      catPet: '宠物',
+      petEnable: '显示桌面宠物',
+      petNote: '宠物浮在界面右下角：拖动换位置，松手会记住；点一下它有反应。',
+      petSize: '宠物大小',
+      petAction: '动作列表',
+      petLoop: '循环',
+      petOnce: '单次',
+      petReset: '归位',
+      petHide: '隐藏',
+      petMenuActions: '动作',
+      petEmpty: '没有找到宠物素材（builtin/宠物）',
+      petSaved: '已保存',
       // ── 更新公告（第四个页签；正文来自 /update 带回的 Release body）──
       catRelease: '更新公告',
       annHead: 'v{version} 更新了什么',
@@ -156,6 +173,19 @@ window.__ModuleLoader__.load({
       updateChecking: 'Checking for updates…',
       updateLatest: 'Up to date',
       updateUnknown: 'Update check unavailable',
+      // ── Pet (third tab; overlay + settings copy) ──
+      catPet: 'Pet',
+      petEnable: 'Show desktop pet',
+      petNote: 'The pet floats in the bottom-right corner: drag it to move, it remembers where you left it, click it for a reaction.',
+      petSize: 'Pet size',
+      petAction: 'Actions',
+      petLoop: 'loop',
+      petOnce: 'once',
+      petReset: 'Reset position',
+      petHide: 'Hide',
+      petMenuActions: 'Actions',
+      petEmpty: 'No pet clips found (builtin/宠物)',
+      petSaved: 'Saved',
       // ── What's new (fourth tab; body comes from the Release notes /update returns) ──
       catRelease: "What's new",
       annHead: 'What changed in v{version}',
@@ -206,6 +236,9 @@ window.__ModuleLoader__.load({
 .dsa-set-desc { font-size: 13px; line-height: 1.55; color: var(--dsw-alias-label-secondary); margin-bottom: 10px; max-width: 720px; }
 .dsa-set-row { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 12px 0; border-bottom: 1px solid var(--dsw-alias-border-l1); }
 .dsa-set-row:last-of-type { border-bottom: none; }
+/* 动作区：标题行 + 整宽的卡片网格（动作数量跟着素材目录长，不用改代码）。 */
+.dsa-set-stack { padding: 12px 0; border-bottom: 1px solid var(--dsw-alias-border-l1); }
+.dsa-set-stack-head { display: flex; align-items: center; justify-content: space-between; gap: 16px; }
 .dsa-set-label { font-size: 13.5px; color: var(--dsw-alias-label-primary); }
 .dsa-set-note { font-size: 12px; color: var(--dsw-alias-label-tertiary); margin-top: 3px; }
 .dsa-set-right { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }
@@ -230,6 +263,15 @@ window.__ModuleLoader__.load({
 .dsa-set-sec { font-size: 13px; color: var(--dsw-alias-label-primary); min-width: 52px; text-align: right; font-variant-numeric: tabular-nums; }
 .dsa-set-range { width: 180px; accent-color: var(--dsw-alias-brand-primary); cursor: pointer; }
 .dsa-set-range:focus-visible { outline: 2px solid var(--dsw-alias-brand-primary); outline-offset: 2px; }
+/* 动作列表：一格一个动作，名字 + 播放方式；正在演的那个描边高亮。 */
+.dsa-set-acts { display: grid; grid-template-columns: repeat(auto-fill, minmax(150px, 1fr)); gap: 10px; margin-top: 12px; }
+.dsa-set-act { display: flex; flex-direction: column; gap: 3px; align-items: flex-start; padding: 10px 12px; border: 1px solid var(--dsw-alias-border-l1); border-radius: 10px; background: var(--dsw-alias-bg-layer-1); font: inherit; color: var(--dsw-alias-label-primary); text-align: left; cursor: pointer; transition: border-color 120ms ease, background 120ms ease; }
+.dsa-set-act:hover { background: var(--dsw-alias-bg-layer-2); }
+.dsa-set-act:focus-visible { outline: 2px solid var(--dsw-alias-brand-primary); outline-offset: 1px; }
+.dsa-set-act[data-on="1"] { border-color: var(--dsw-alias-brand-primary); background: var(--dsw-alias-bg-layer-2); }
+.dsa-set-act:disabled { opacity: 0.55; cursor: default; pointer-events: none; }
+.dsa-set-act-name { font-size: 13px; line-height: 1.4; }
+.dsa-set-act-kind { font-size: 11.5px; line-height: 1.2; color: var(--dsw-alias-label-tertiary); }
 .dsa-set-empty { font-size: 12.5px; color: var(--dsw-alias-label-tertiary); padding: 10px 0; }
 /* ── 当前素材预览（设置区素材行）── */
 .dsa-set-cur { display: flex; align-items: center; gap: 10px; min-width: 0; }
@@ -713,8 +755,545 @@ window.__ModuleLoader__.load({
       return lines
     }
 
+    // ──────────────────────────────────────────────────────────────
+    // 宠物浮层
+    // ──────────────────────────────────────────────────────────────
+
     /**
-     * 「启动动画」页：常驻设置区 + 下方 [MP4|壁纸|音频|更新公告] 分类切换器与内容面板。
+     * 素材的宽高比（高 ÷ 宽）：480×648。
+     *
+     * 必须和 `tools/make-pet-assets.mjs` 的 `CROP` 一致 —— 素材是裁好再发的，
+     * 客户端只能按这个比例算高度（没有别的地方知道真实尺寸）。换裁剪窗口时两处一起改。
+     */
+    const PET_ASPECT = 648 / 480
+    /** 轮播里两个动作之间的定格时长：动作演完一遍停住，隔这么久再演下一个。 */
+    const PET_GAP_MS = 3000
+
+    /** 浮层样式。挂 body 的常驻元素，不走组件局部样式，单独注入一份 <style>。 */
+    const PET_STYLE = `
+.dsa-pet { position: fixed; left: 0; top: 0; z-index: 999999; pointer-events: none; }
+.dsa-pet[data-on="0"] { display: none; }
+.dsa-pet-stage { position: relative; display: grid; pointer-events: auto; cursor: grab; touch-action: none; user-select: none; -webkit-user-select: none; transform-origin: 50% 88%; transition: transform 210ms cubic-bezier(.22, 1.4, .36, 1); }
+.dsa-pet-stage[data-drag="1"] { cursor: grabbing; transition: none; }
+/* 三段动画叠在同一格：切换只改 opacity，不增删 DOM —— 重建 video 要重新解码，会明显闪。 */
+.dsa-pet-video { grid-area: 1 / 1; width: 100%; height: auto; display: block; opacity: 0; transition: opacity 140ms linear; pointer-events: none; }
+.dsa-pet-video[data-on="1"] { opacity: 1; }
+/* 右键菜单：跟随应用深浅色（同一份文档，--dsw-alias-* 全局可用）。 */
+.dsa-pet-menu { position: fixed; z-index: 1000000; min-width: 150px; max-height: 62vh; overflow: auto; overscroll-behavior: contain; padding: 6px; border-radius: 10px; border: 1px solid var(--dsw-alias-border-l1, rgba(128,128,128,.35)); background: var(--dsw-alias-bg-layer-1, #fff); box-shadow: 0 10px 28px rgba(0, 0, 0, 0.16); }
+.dsa-pet-menu-head { font-size: 11px; color: var(--dsw-alias-label-tertiary, #999); padding: 4px 8px 2px; }
+.dsa-pet-menu-item { display: block; width: 100%; text-align: left; font: inherit; font-size: 12.5px; color: var(--dsw-alias-label-primary, #333); background: none; border: 0; border-radius: 6px; padding: 6px 8px; cursor: pointer; white-space: nowrap; }
+.dsa-pet-menu-item:hover { background: var(--dsw-alias-bg-layer-2, rgba(128, 128, 128, 0.12)); }
+.dsa-pet-menu-item[data-on="1"] { color: var(--dsw-alias-brand-primary, #4b6bfb); }
+.dsa-pet-menu-sep { height: 1px; margin: 5px 6px; background: var(--dsw-alias-border-l1, rgba(128, 128, 128, 0.25)); }
+`
+
+    /**
+     * 桌面宠物浮层。
+     *
+     * 为什么不用 React：它挂在 `document.body` 上，生命周期跨整个应用，和设置页的
+     * 渲染树没有关系（关掉设置页宠物还在）。原生 DOM 让"进设置页才创建、退出就
+     * 销毁"这类错误不可能发生，也省掉一次 createRoot。
+     *
+     * 位置口径：`x/y` 是 0–100 的百分比，表示"在可移动区间里的比例"
+     * （0 = 贴左/贴上，100 = 贴右/贴下），所以窗口缩放后宠物仍然贴着同一角，
+     * 也不会跑到屏幕外。像素位置 = 百分比 × (视口 − 宠物尺寸)。
+     *
+     * @param {{ onPersist: (patch: object) => void, t: (key: string) => string }} options 位置落盘回调 + 菜单文案。
+     * @returns {{ load: () => Promise<void>, sync: (pet: object) => void, play: (id: string) => void, report: () => void, reset: () => void, destroy: () => void }} 浮层控制器。
+     */
+    function createPetOverlay(options) {
+      const onPersist = options.onPersist
+      const t = options.t
+      /** @type {HTMLStyleElement | null} */
+      let styleEl = null
+      /** @type {HTMLDivElement | null} */
+      let host = null
+      /** @type {HTMLDivElement | null} */
+      let stage = null
+      /** @type {Map<string, HTMLVideoElement>} */
+      const videos = new Map()
+      /** 已构建的清单指纹：只有动作清单变了才重建 video。 */
+      let builtKey = ''
+      /** 当前配置快照（位置字段只在 load/reset 时采纳，见 sync 的注释）。 */
+      let pet = { enabled: false, size: 176, x: 100, y: 100, idle: '', click: '', drag: '', clips: [] }
+      let current = ''
+      /** @type {{ id: number, dx: number, dy: number, startX: number, startY: number, moved: boolean } | null} */
+      let drag = null
+      let frame = 0
+      // ── 轮播状态机：动作按清单顺序演，演完一遍定格 PET_GAP_MS 再下一个 ──
+      /** 轮播位置（clips 的下标）。手动点播会把位置挪到那个动作上，播完从它下一个继续。 */
+      let carouselIndex = 0
+      /** 定格计时器（0 = 没有在定格）。 */
+      let gapTimer = 0
+      /** 当前动作播完（ended）之后要去哪：轮播/点播都会排一个回调进去。 */
+      let afterEnded = null
+      /** @type {HTMLDivElement | null} 右键菜单（同一时刻至多一个）。 */
+      let menu = null
+
+      /** 注入一次样式（重复调用安全）。 */
+      const ensureStyle = () => {
+        if (styleEl !== null) return
+        styleEl = document.createElement('style')
+        styleEl.setAttribute('data-dsa-pet', '')
+        styleEl.textContent = PET_STYLE
+        document.head.appendChild(styleEl)
+      }
+
+      /**
+       * 按当前清单建 DOM。只建一次 —— 清单没变就不动，避免每次状态回包都重新解码。
+       */
+      const build = () => {
+        const key = pet.clips.map((clip) => `${clip.id}:${clip.file}`).join('|')
+        if (key === builtKey) return
+        builtKey = key
+        ensureStyle()
+        if (host === null) {
+          host = document.createElement('div')
+          host.className = 'dsa-pet'
+          host.dataset.on = '0'
+          stage = document.createElement('div')
+          stage.className = 'dsa-pet-stage'
+          host.appendChild(stage)
+          document.body.appendChild(host)
+        }
+        if (stage === null) return
+        // 换素材（未来支持多套宠物时）才需要清空；同一清单重复调用在上面就返回了。
+        for (const [, el] of videos) el.remove()
+        videos.clear()
+        current = ''
+        for (const clip of pet.clips) {
+          const video = document.createElement('video')
+          video.className = 'dsa-pet-video'
+          video.src = `${ASSET}?path=${encodeURIComponent(clip.file)}`
+          video.muted = true
+          video.loop = clip.loop === true
+          video.playsInline = true
+          video.preload = 'auto'
+          video.setAttribute('aria-hidden', 'true')
+          video.dataset.clip = clip.id
+          // 所有动作统一在 ended 里接"播完之后"的回调：轮播接"定格后下一个"，
+          // 点播接"定格后从下一个继续"。循环素材在轮播/点播时会被临时改成单遍。
+          video.addEventListener('ended', () => {
+            if (current !== clip.id) return
+            const after = afterEnded
+            afterEnded = null
+            if (after !== null) after()
+          })
+          stage.appendChild(video)
+          videos.set(clip.id, video)
+        }
+      }
+
+      /** 把百分比位置换算成像素并应用（窗口尺寸变了就重算）。 */
+      const layout = () => {
+        if (host === null) return
+        const width = pet.size
+        const height = Math.round(width * PET_ASPECT)
+        const maxLeft = Math.max(0, window.innerWidth - width)
+        const maxTop = Math.max(0, window.innerHeight - height)
+        host.style.width = `${width}px`
+        host.style.left = `${Math.round((maxLeft * pet.x) / 100)}px`
+        host.style.top = `${Math.round((maxTop * pet.y) / 100)}px`
+      }
+
+      /** 暂停所有视频（关掉宠物时调用：不在后台白烧解码）。 */
+      const pauseAll = () => {
+        for (const [, video] of videos) {
+          try {
+            video.pause()
+          } catch {
+            /* 已停 */
+          }
+        }
+      }
+
+      /**
+       * 切到某个动作。
+       * @param {string} id 动作 id（即素材文件名去扩展名，见宿主返回的 pet.clips）。
+       */
+      const show = (id) => {
+        const video = videos.get(id)
+        // 动作缺失（用户只放了部分素材）就退回待机，不留一个空白框。
+        if (video === undefined) {
+          if (id !== pet.idle) show(pet.idle)
+          return
+        }
+        // 注意这里**不能**因为"已经在演这个动作"就早退：show 兼着"重播一遍"的职责
+        // （轮播/点播都要从头演）。早退会让"点播当前正在演的动作"变成什么都不发生，
+        // 那一轮排好的"演完接下一个"也就永远不会触发 —— 宠物就此卡住。
+        current = id
+        for (const [key, el] of videos) {
+          if (key === id) continue
+          el.dataset.on = '0'
+          // 淡出跑完再暂停：立刻 pause 会让上一段定在最后一帧，交叉时看得见。
+          window.setTimeout(() => {
+            if (current !== key) {
+              try {
+                el.pause()
+              } catch {
+                /* 已停 */
+              }
+            }
+          }, 160)
+        }
+        video.dataset.on = '1'
+        try {
+          video.currentTime = 0
+        } catch {
+          /* 还没元数据，play 之后自己从头播 */
+        }
+        const played = video.play()
+        if (played && typeof played.catch === 'function') played.catch(() => {})
+        // 告诉设置页"现在在演哪一段"，动作列表据此高亮（宠物也可能自己切，比如回应播完）。
+        window.dispatchEvent(new CustomEvent('dsa:pet-state', { detail: id }))
+      }
+
+      /**
+       * 回报当前动作（设置页刚挂载时问一次）。
+       *
+       * 为什么需要：宠物在页面加载时就开播待机了，那一刻设置页还没渲染，事件没人听；
+       * 等用户翻到宠物页签时，高亮会是空的。让设置页主动问一声，两边状态就对齐了。
+       */
+      const report = () => {
+        if (current !== '') window.dispatchEvent(new CustomEvent('dsa:pet-state', { detail: current }))
+      }
+
+      // ── 轮播 / 点播 ──
+      //
+      // 节奏：每个动作演**一遍**（循环素材临时关掉 loop），end 后定格在最后一帧
+      // PET_GAP_MS，再演下一个；到表尾绕回第一个。手动点播（右键菜单 / 左键点击）
+      // 是插队：演完从"那个动作的下一个"继续轮播。
+
+      /** 清掉定格计时器。 */
+      const clearGap = () => {
+        if (gapTimer !== 0) {
+          window.clearTimeout(gapTimer)
+          gapTimer = 0
+        }
+      }
+
+      /** 轮播彻底停下（关宠物 / 拖拽接管时用）。 */
+      const stopSequence = () => {
+        clearGap()
+        afterEnded = null
+      }
+
+      /**
+       * 播一个动作**一遍**，播完把控制权交给 `after`。
+       * 与 show 的区别：临时关掉 loop，让 ended 事件能告诉我们"演完了"。
+       */
+      const playOnce = (id, after) => {
+        const video = videos.get(id)
+        if (video === undefined) {
+          // 动作缺失（清单和素材不同步）就跳过它，节奏不能断。
+          after()
+          return
+        }
+        clearGap()
+        afterEnded = after
+        video.loop = false
+        show(id)
+      }
+
+      /** 从序列的第 index 个开始轮播（越界自动绕回）。 */
+      const playCarouselAt = (index) => {
+        const count = pet.clips.length
+        if (!pet.enabled || count === 0) return
+        carouselIndex = ((index % count) + count) % count
+        playOnce(pet.clips[carouselIndex].id, () => {
+          gapTimer = window.setTimeout(() => playCarouselAt(carouselIndex + 1), PET_GAP_MS)
+        })
+      }
+
+      /**
+       * 手动点播：演 `id` 一遍，定格后从**它的下一个**继续轮播。
+       * 右键菜单和左键点击都走这里 —— 对轮播来说是同一种"插队"。
+       */
+      const playManual = (id) => {
+        const at = pet.clips.findIndex((clip) => clip.id === id)
+        if (at < 0) return
+        // 轮播位置要跟着挪到点播的那个动作上：不然中途被打断（拖拽）再恢复，
+        // 会从旧位置接着演，而不是从"点播动作的下一个"接着演。
+        carouselIndex = at
+        playOnce(id, () => {
+          gapTimer = window.setTimeout(() => playCarouselAt(at + 1), PET_GAP_MS)
+        })
+      }
+
+      /**
+       * 恢复轮播：**立刻**演下一个。
+       *
+       * 为什么不等那 3 秒间隔：间隔是"两个动作之间"的节奏，而这里是**用户主动打断**
+       * 之后回来（拖拽松手）。再等 3 秒，画面就停在被打断动作的最后一帧上不动 ——
+       * 看着像卡住了。间隔留给轮播本身，打断后立刻接上。
+       */
+      const resumeCarousel = () => {
+        clearGap()
+        afterEnded = null
+        playCarouselAt(carouselIndex + 1)
+      }
+
+      // ── 右键菜单 ──
+
+      const closeMenu = () => {
+        if (menu !== null) {
+          menu.remove()
+          menu = null
+          document.removeEventListener('pointerdown', onMenuDocDown, true)
+        }
+      }
+
+      /** 点菜单以外的地方就收起（capture 阶段拦，抢在拖拽/点击处理之前）。 */
+      const onMenuDocDown = (event) => {
+        if (menu !== null && event.target instanceof Node && !menu.contains(event.target)) closeMenu()
+      }
+
+      const menuItem = (label, onClick, on) => {
+        const item = document.createElement('button')
+        item.type = 'button'
+        item.className = 'dsa-pet-menu-item'
+        item.textContent = label
+        item.dataset.on = on ? '1' : '0'
+        item.addEventListener('click', () => {
+          closeMenu()
+          onClick()
+        })
+        return item
+      }
+
+      /** 右键菜单：「动作」列表 + 归位 + 隐藏。列表来自 pet.clips，加动作自动出现。 */
+      const openMenu = (x, y) => {
+        closeMenu()
+        ensureStyle()
+        menu = document.createElement('div')
+        menu.className = 'dsa-pet-menu'
+        const head = document.createElement('div')
+        head.className = 'dsa-pet-menu-head'
+        head.textContent = options.t('petMenuActions')
+        menu.appendChild(head)
+        for (const clip of pet.clips) {
+          menu.appendChild(menuItem(clip.name, () => playManual(clip.id), current === clip.id))
+        }
+        menu.appendChild(Object.assign(document.createElement('div'), { className: 'dsa-pet-menu-sep' }))
+        menu.appendChild(
+          menuItem(options.t('petReset'), () => {
+            reset()
+          }, false),
+        )
+        menu.appendChild(menuItem(options.t('petHide'), hideSelf, false))
+        document.body.appendChild(menu)
+        // 贴着鼠标展开，但不许出屏。
+        const rect = menu.getBoundingClientRect()
+        const left = Math.max(4, Math.min(x, window.innerWidth - rect.width - 4))
+        const top = Math.max(4, Math.min(y, window.innerHeight - rect.height - 4))
+        menu.style.left = `${Math.round(left)}px`
+        menu.style.top = `${Math.round(top)}px`
+        document.addEventListener('pointerdown', onMenuDocDown, true)
+      }
+
+      /** 菜单里的"隐藏"：等于设置页那个总开关，落盘后浮层会随 sync 自己收起来。 */
+      const hideSelf = () => {
+        stopSequence()
+        onPersist({ petEnabled: false })
+      }
+
+      /** 把当前像素位置写回百分比并落盘（拖动结束时调用）。 */
+      const commitPosition = () => {
+        if (host === null) return
+        const width = pet.size
+        const height = Math.round(width * PET_ASPECT)
+        const maxLeft = Math.max(1, window.innerWidth - width)
+        const maxTop = Math.max(1, window.innerHeight - height)
+        const left = Number.parseFloat(host.style.left) || 0
+        const top = Number.parseFloat(host.style.top) || 0
+        pet.x = Math.max(0, Math.min(100, Math.round((left / maxLeft) * 1000) / 10))
+        pet.y = Math.max(0, Math.min(100, Math.round((top / maxTop) * 1000) / 10))
+        onPersist({ petX: pet.x, petY: pet.y })
+      }
+
+      /** 拖动开始：接管指针、切到拖拽动作。 */
+      const onPointerDown = (event) => {
+        if (event.button !== 0 || host === null || !pet.enabled) return
+        closeMenu()
+        const rect = host.getBoundingClientRect()
+        drag = {
+          id: event.pointerId,
+          dx: event.clientX - rect.left,
+          dy: event.clientY - rect.top,
+          startX: event.clientX,
+          startY: event.clientY,
+          moved: false,
+        }
+        stage.dataset.drag = '1'
+        try {
+          stage.setPointerCapture(event.pointerId)
+        } catch {
+          /* 某些浏览器对非活动指针会抛，拖拽仍可用 */
+        }
+        // 拖拽接管轮播：被拎着的时候循环演"拖拽悬空"（没有这个角色就保持当前动作）。
+        stopSequence()
+        if (pet.drag !== '') {
+          const dragVideo = videos.get(pet.drag)
+          if (dragVideo !== undefined) dragVideo.loop = true
+          show(pet.drag)
+        }
+        event.preventDefault()
+      }
+
+      const onPointerMove = (event) => {
+        if (drag === null || event.pointerId !== drag.id || host === null) return
+        const dx = event.clientX - drag.startX
+        const dy = event.clientY - drag.startY
+        // 4px 门槛：点击时手会抖一两像素，不该被当成拖拽。
+        if (!drag.moved && Math.hypot(dx, dy) < 4) return
+        drag.moved = true
+        const width = pet.size
+        const height = Math.round(width * PET_ASPECT)
+        const maxLeft = Math.max(0, window.innerWidth - width)
+        const maxTop = Math.max(0, window.innerHeight - height)
+        const left = Math.max(0, Math.min(maxLeft, event.clientX - drag.dx))
+        const top = Math.max(0, Math.min(maxTop, event.clientY - drag.dy))
+        host.style.left = `${Math.round(left)}px`
+        host.style.top = `${Math.round(top)}px`
+        // 被拎起来的那点手感：往哪边甩就往哪边倒，最多 9°。
+        stage.style.transform = `rotate(${Math.max(-9, Math.min(9, dx * 0.12)).toFixed(1)}deg)`
+      }
+
+      const onPointerUp = (event) => {
+        if (drag === null || event.pointerId !== drag.id) return
+        const moved = drag.moved
+        drag = null
+        if (stage !== null) {
+          stage.dataset.drag = '0'
+          stage.style.transform = ''
+        }
+        try {
+          stage.releasePointerCapture(event.pointerId)
+        } catch {
+          /* 已经释放 */
+        }
+        if (moved) {
+          commitPosition()
+          // 拖拽结束：把"拖拽悬空"定格在当前帧，隔一会儿从轮播的下一个接着演。
+          if (pet.drag !== '') {
+            const dragVideo = videos.get(pet.drag)
+            if (dragVideo !== undefined) {
+              try {
+                dragVideo.pause()
+              } catch {
+                /* 已停 */
+              }
+            }
+          }
+          resumeCarousel()
+        } else if (pet.click !== '') {
+          // 没位移 = 一次点击：插播"点击回应"，演完从它的下一个继续轮播。
+          playManual(pet.click)
+        } else {
+          resumeCarousel()
+        }
+      }
+
+      const onResize = () => {
+        if (frame !== 0) return
+        frame = window.requestAnimationFrame(() => {
+          frame = 0
+          layout()
+        })
+      }
+
+      const bind = () => {
+        if (stage === null || stage.dataset.bound === '1') return
+        stage.dataset.bound = '1'
+        stage.addEventListener('pointerdown', onPointerDown)
+        stage.addEventListener('pointermove', onPointerMove)
+        stage.addEventListener('pointerup', onPointerUp)
+        stage.addEventListener('pointercancel', onPointerUp)
+        // 右键：动作菜单。浏览器默认菜单拦掉。
+        stage.addEventListener('contextmenu', (event) => {
+          if (!pet.enabled) return
+          event.preventDefault()
+          openMenu(event.clientX, event.clientY)
+        })
+        window.addEventListener('resize', onResize)
+      }
+
+      /** 首次从服务端取状态（失败就安静地不出现 —— 宠物是装饰，不该报错）。 */
+      const load = () =>
+        fetch(MANAGE, { cache: 'no-store' })
+          .then((res) => res.json())
+          .then((payload) => {
+            if (!payload || !payload.ok || !payload.pet) return
+            pet.x = typeof payload.pet.x === 'number' ? payload.pet.x : pet.x
+            pet.y = typeof payload.pet.y === 'number' ? payload.pet.y : pet.y
+            sync(payload.pet)
+          })
+          .catch(() => {})
+
+      /**
+       * 应用一份新配置（开关 / 大小 / 动作清单）。
+       *
+       * **不采纳 x/y**：位置由本浮层独占（拖动后自己写盘）。设置页每次写别的字段都会
+       * 拿到一份状态回包，如果那份回包里的旧坐标也被应用，宠物会被拽回上一次保存的位置。
+       *
+       * @param {object} next 服务端给的 pet 状态。
+       */
+      const sync = (next) => {
+        if (!next || typeof next !== 'object') return
+        pet.enabled = next.enabled === true
+        if (typeof next.size === 'number' && Number.isFinite(next.size)) pet.size = next.size
+        if (Array.isArray(next.clips) && next.clips.length > 0) pet.clips = next.clips
+        // 三个语义角色由宿主给：待机 / 点击时播哪个 / 拖动时播哪个。
+        for (const role of ['idle', 'click', 'drag']) {
+          if (typeof next[role] === 'string') pet[role] = next[role]
+        }
+        // 关着的时候**不建 DOM**：九段素材加起来 4 MB，没开宠物就不该占用户的带宽
+        // 和内存。打开时才建，那一次开销是用户自己按出来的。
+        if (!pet.enabled) {
+          stopSequence()
+          closeMenu()
+          pauseAll()
+          current = ''
+          if (host !== null) host.dataset.on = '0'
+          return
+        }
+        build()
+        bind()
+        layout()
+        if (host !== null) host.dataset.on = '1'
+        if (current === '') playCarouselAt(carouselIndex)
+      }
+
+      /** 归位：回到右下角并落盘。 */
+      const reset = () => {
+        pet.x = 100
+        pet.y = 100
+        layout()
+        onPersist({ petX: 100, petY: 100 })
+      }
+
+      const destroy = () => {
+        window.removeEventListener('resize', onResize)
+        if (frame !== 0) window.cancelAnimationFrame(frame)
+        frame = 0
+        stopSequence()
+        closeMenu()
+        pauseAll()
+        videos.clear()
+        if (host !== null) host.remove()
+        if (styleEl !== null) styleEl.remove()
+        host = null
+        stage = null
+        styleEl = null
+        builtKey = ''
+      }
+
+      // play = 手动点播：设置页的动作卡和右键菜单都走这条 —— 演一遍然后从下一个继续轮播。
+      return { load, sync, play: playManual, report, reset, destroy }
+    }
+
+    /**
+     * 「启动动画」页：常驻设置区 + 下方 [MP4|壁纸|音频|宠物|更新公告] 分类切换器与内容面板。
      * @param {(key: string) => string} t 翻译。
      * @returns {React.ComponentType} 页面组件。
      */
@@ -739,6 +1318,11 @@ window.__ModuleLoader__.load({
         const avolRef = React.useRef(null)
         const [playingPath, setPlayingPath] = React.useState('')
         const audioElRef = React.useRef(null)
+        // 宠物：大小滑杆的本地读数（拖动时只改本地，停手再提交）。
+        const [petSize, setPetSize] = React.useState(176)
+        const petSizeRef = React.useRef(null)
+        /** 宠物此刻在演哪个动作 —— 由浮层回报，用来高亮动作列表（它自己也会切，比如回应播完）。 */
+        const [activeClip, setActiveClip] = React.useState('')
         // ── 卸载 / 更新（v1.11.0）──
         // 自管状态：宿主在 profile 里有没有装我们、有没有选中、装的是什么形态。
         const [selfState, setSelfState] = React.useState(null)
@@ -748,8 +1332,25 @@ window.__ModuleLoader__.load({
         React.useEffect(() => {
           if (state && typeof state.durationSec === 'number') setSec(state.durationSec)
           if (state && typeof state.audioVolume === 'number') setAvol(Math.round(state.audioVolume * 100))
+          if (state && state.pet && typeof state.pet.size === 'number') setPetSize(state.pet.size)
         }, [state])
 
+        // 设置页里的改动（开关 / 大小）要立刻反映到浮层上：两边不在同一棵渲染树上，
+        // 用一条 window 事件桥接。浮层只取 enabled/size/clips，位置它自己管。
+        React.useEffect(() => {
+          if (!state || !state.pet) return
+          window.dispatchEvent(new CustomEvent('dsa:pet-sync', { detail: state.pet }))
+        }, [state])
+
+        // 反过来：浮层切了动作就回报一声，列表跟着高亮。
+        React.useEffect(() => {
+          const onState = (event) => setActiveClip(typeof event.detail === 'string' ? event.detail : '')
+          window.addEventListener('dsa:pet-state', onState)
+          // 先挂监听再问：宠物在页面加载时就开播了，那会儿没人听。
+          window.dispatchEvent(new CustomEvent('dsa:pet-query'))
+          return () => window.removeEventListener('dsa:pet-state', onState)
+        }, [])
+
         // 首次拿到状态时，把分类切换器对齐到当前使用的素材（只做一次，之后尊重手动切换）。
         React.useEffect(() => {
           if (!state || syncedRef.current) return
@@ -775,6 +1376,7 @@ window.__ModuleLoader__.load({
           () => () => {
             if (commitRef.current !== null) clearTimeout(commitRef.current)
             if (avolRef.current !== null) clearTimeout(avolRef.current)
+            if (petSizeRef.current !== null) clearTimeout(petSizeRef.current)
             if (audioElRef.current !== null) {
               try {
                 audioElRef.current.pause()
@@ -818,8 +1420,40 @@ window.__ModuleLoader__.load({
           }, 350)
         }
 
-        /** 试听/停止一条音频（列表内点击，不影响开机配置）。 */
-        const togglePlay = (file) => {
+        // 宠物大小：同展示时长的防抖方式（停手 350ms 提交一次）。
+        const onPetSize = (value) => {
+          const next = Math.min(320, Math.max(100, Math.round(Number(value))))
+          setPetSize(next)
+          if (petSizeRef.current !== null) clearTimeout(petSizeRef.current)
+          petSizeRef.current = setTimeout(() => {
+            petSizeRef.current = null
+            postJson(send, { petSize: next }, t('petSaved'))
+          }, 350)
+        }
+
+        /** 宠物开关：字段在 state.pet 里，不走通用 toggle（那个读的是顶层字段）。 */
+        const togglePet = () => {
+          if (!state || !state.pet) return
+          postJson(send, { petEnabled: !state.pet.enabled }, t('petSaved'))
+        }
+
+        /** 动作预览：让浮层立刻播一段（不写配置，纯预览）。宠物没开就先打开它 —— 用户按了按钮就是要看。 */
+        const previewPet = (id) => {
+          const fire = () => window.dispatchEvent(new CustomEvent('dsa:pet-play', { detail: id }))
+          if (state && state.pet && !state.pet.enabled) {
+            void postJson(send, { petEnabled: true }, t('petSaved')).then((payload) => {
+              if (!payload || !payload.ok) return
+              // 先把新状态推给浮层（它要在这之后才有 DOM 可播），再发播放事件。
+              // 只靠 effect 那条路会有一个"打开还没渲染完就播"的空窗。
+              if (payload.pet) window.dispatchEvent(new CustomEvent('dsa:pet-sync', { detail: payload.pet }))
+              setTimeout(fire, 60)
+            })
+            return
+          }
+          fire()
+        }
+
+        /** 试听/停止一条音频（列表内点击，不影响开机配置）。 */        const togglePlay = (file) => {
           if (audioElRef.current !== null) {
             try {
               audioElRef.current.pause()
@@ -1013,10 +1647,19 @@ window.__ModuleLoader__.load({
         const files = categoryData ? categoryData.files : []
         const activeFile = state ? state.file : ''
         const activeAudio = state ? state.audioFile : ''
-        const categoryLabel = category === 'mp4' ? t('catMp4') : category === 'wall' ? t('catWall') : t('catAudio')
+        const categoryLabel =
+          category === 'pet'
+            ? t('catPet')
+            : category === 'mp4'
+              ? t('catMp4')
+              : category === 'wall'
+                ? t('catWall')
+                : t('catAudio')
         const isAudioCat = category === 'audio'
         // 第四个页签不是素材分类：它没有上传、没有卡片，内容是 /update 带回的 Release 正文。
         const isReleaseCat = category === 'release'
+        // 宠物页签同理：长得像分类，其实是"宠物设置 + 动作预览"。
+        const isPetCat = category === 'pet'
 
         /**
          * 标题旁的版本小字。
@@ -1335,6 +1978,98 @@ window.__ModuleLoader__.load({
                 ),
         )
 
+        /**
+         * 宠物面板：开关 + 大小 + 动作列表。
+         *
+         * 动作**不写死**：清单来自宿主扫描 `builtin/宠物/`，丢一个新 webm 进去就多一条。
+         * 每格写着名字和「循环 / 单次」，正在演的那格描边高亮（浮层切动作时会回报）。
+         */
+        const pet = state && state.pet && typeof state.pet === 'object' ? state.pet : null
+        const petClips = pet && Array.isArray(pet.clips) ? pet.clips : []
+        const petSwitch = h(
+          'button',
+          {
+            type: 'button',
+            className: 'dsa-set-switch',
+            role: 'switch',
+            'aria-checked': pet && pet.enabled ? 'true' : 'false',
+            'aria-label': t('petEnable'),
+            disabled: busy || pet === null,
+            onClick: togglePet,
+          },
+          h('span', { className: 'dsa-set-knob' }),
+        )
+        const petResetBtn = h(
+          'button',
+          {
+            type: 'button',
+            className: 'dsa-set-btn',
+            disabled: busy || pet === null || !pet.enabled,
+            onClick: () => window.dispatchEvent(new CustomEvent('dsa:pet-reset')),
+          },
+          t('petReset'),
+        )
+        /** 一个动作 = 一个格子。宠物没开也能按（会先打开它），按了就该看到反应。 */
+        const petClipCard = (clip) =>
+          h(
+            'button',
+            {
+              key: clip.id,
+              type: 'button',
+              className: 'dsa-set-act',
+              'data-on': activeClip === clip.id ? '1' : '0',
+              'aria-pressed': activeClip === clip.id ? 'true' : 'false',
+              disabled: busy || pet === null,
+              onClick: () => previewPet(clip.id),
+            },
+            h('span', { className: 'dsa-set-act-name' }, clip.name),
+            h('span', { className: 'dsa-set-act-kind' }, clip.loop === false ? t('petOnce') : t('petLoop')),
+          )
+        const petPanel = h(
+          'div',
+          { className: 'dsa-set-panel', role: 'tabpanel', 'aria-label': t('catPet') },
+          h('div', { className: 'dsa-set-desc' }, t('petNote')),
+          h(
+            'div',
+            { className: 'dsa-set-row' },
+            h('div', { className: 'dsa-set-label' }, t('petEnable')),
+            h('div', { className: 'dsa-set-right' }, petSwitch),
+          ),
+          h(
+            'div',
+            { className: 'dsa-set-row' },
+            h('div', { className: 'dsa-set-label' }, t('petSize')),
+            h(
+              'div',
+              { className: 'dsa-set-right' },
+              h('span', { className: 'dsa-set-sec' }, `${petSize}px`),
+              h('input', {
+                type: 'range',
+                className: 'dsa-set-range',
+                min: 100,
+                max: 320,
+                step: 4,
+                value: petSize,
+                'aria-label': t('petSize'),
+                onChange: (event) => onPetSize(event.target.value),
+              }),
+            ),
+          ),
+          h(
+            'div',
+            { className: 'dsa-set-stack' },
+            h(
+              'div',
+              { className: 'dsa-set-stack-head' },
+              h('div', { className: 'dsa-set-label' }, t('petAction')),
+              h('div', { className: 'dsa-set-right' }, petResetBtn),
+            ),
+            petClips.length === 0
+              ? h('div', { className: 'dsa-set-empty' }, t('petEmpty'))
+              : h('div', { className: 'dsa-set-acts' }, petClips.map(petClipCard)),
+          ),
+        )
+
         return h(
           'div',
           { className: 'dsa-set-wrap', 'data-busy': busy ? '1' : '0' },
@@ -1486,7 +2221,7 @@ window.__ModuleLoader__.load({
               ),
             ),
           ),
-          // ── 分类切换器：[MP4 | 壁纸 | 音频 | 更新公告]（素材三类 + 一个信息页）──
+          // ── 分类切换器：[MP4 | 壁纸 | 音频 | 宠物 | 更新公告]（素材三类 + 宠物 + 一个信息页）──
           h(
             'div',
             { className: 'dsa-set-tabs', role: 'tablist', 'aria-label': t('title') },
@@ -1494,6 +2229,7 @@ window.__ModuleLoader__.load({
               { id: 'mp4', label: t('catMp4') },
               { id: 'wall', label: t('catWall') },
               { id: 'audio', label: t('catAudio') },
+              { id: 'pet', label: t('catPet') },
               { id: 'release', label: t('catRelease') },
             ].map((entry) =>
               h(
@@ -1515,7 +2251,7 @@ window.__ModuleLoader__.load({
               ),
             ),
           ),
-          isReleaseCat ? releasePanel : categoryPanel,
+          isReleaseCat ? releasePanel : isPetCat ? petPanel : categoryPanel,
           // 上传输入随分类切换 accept。
           h('input', {
             ref: fileRef,
@@ -1550,7 +2286,50 @@ window.__ModuleLoader__.load({
             ),
           )
 
+          // ── 桌面宠物：常驻浮层，和设置页无关（关掉设置页它还在）──
+          //
+          // 位置由浮层自己写盘：拖动结束时 POST 一次 petX/petY。设置页只做
+          // "开关 / 大小 / 触发动作"，两边用 window 事件桥接，互不持有引用。
+          // POST 的回包会广播成 dsa:pet-sync：右键菜单里"隐藏"自己之后，浮层和
+          // 设置页的开关都能立刻对上，不用等用户手动刷新。
+          const petLayer = createPetOverlay({
+            t,
+            onPersist: (patch) => {
+              void fetch(MANAGE, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(patch),
+              })
+                .then((res) => res.json())
+                .then((payload) => {
+                  if (payload && payload.pet) {
+                    window.dispatchEvent(new CustomEvent('dsa:pet-sync', { detail: payload.pet }))
+                  }
+                })
+                .catch(() => {})
+            },
+          })
+          const onPetSync = (event) => petLayer.sync(event.detail)
+          const onPetPlay = (event) => petLayer.play(String(event.detail || ''))
+          const onPetReset = () => petLayer.reset()
+          // 设置页翻到宠物页签时会问一句"现在在演哪个"，好把动作列表的高亮对上。
+          const onPetQuery = () => petLayer.report()
+          window.addEventListener('dsa:pet-sync', onPetSync)
+          window.addEventListener('dsa:pet-play', onPetPlay)
+          window.addEventListener('dsa:pet-reset', onPetReset)
+          window.addEventListener('dsa:pet-query', onPetQuery)
+          void petLayer.load()
+
           return () => {
+            window.removeEventListener('dsa:pet-sync', onPetSync)
+            window.removeEventListener('dsa:pet-play', onPetPlay)
+            window.removeEventListener('dsa:pet-reset', onPetReset)
+            window.removeEventListener('dsa:pet-query', onPetQuery)
+            try {
+              petLayer.destroy()
+            } catch {
+              /* 浮层可能已经因为页面卸载被清掉 */
+            }
             for (const off of [offSlots, offZh, offEn]) {
               try {
                 off && off()

package/index.js

@@ -293,6 +293,42 @@ export const MEDIA_DIR_NAME = 'startup-animation-media'
 /** 内置素材库目录名（包内，随插件分发，见 builtin/README 一节的分类结构）。 */
 export const BUILTIN_DIR_NAME = 'builtin'
 
+/**
+ * 宠物动画目录（包内 `builtin/宠物/`）。
+ *
+ * 它和 MP4 / 图片 / 音频并列放在 `builtin/` 下，但**不是启动素材** ——
+ * 不出现在素材库列表里（scanLibrary 跳过），只由宠物浮层取用。
+ * 加动作就是往这个目录丢一个 `.webm`，**不用改代码**：文件名即动作名。
+ */
+export const PET_DIR_NAME = '宠物'
+
+/**
+ * 宠物动作的语义约定：哪一个文件当"待机"、哪一个是"点击回应"、哪一个演"被拖拽"。
+ *
+ * 只是**声明**，不是白名单 —— 目录里其他 `.webm` 一样会出现在动作列表里（按文件名排序）。
+ * 这三个角色缺失时对应行为降级：没有待机 = 用列表第一个；没有点击回应 = 点了没反应；
+ * 没有拖拽悬空 = 拖动时保持当前动作。
+ */
+export const PET_ROLES = Object.freeze({ idle: '待机', click: '点击回应', drag: '拖拽悬空' })
+
+/**
+ * 已知动作的播放方式：`loop: false` = 播一遍就回待机（点击回应、打招呼这类一次性反应）。
+ *
+ * 没在这里声明的动作默认**循环**播放 —— 新加的动作通常是想让它一直演。
+ * 这份清单同时决定**排列顺序**（没声明的按文件名排在后面）。
+ */
+export const PET_CLIPS = Object.freeze([
+  { id: PET_ROLES.idle, loop: true },
+  { id: PET_ROLES.click, loop: false },
+  { id: '害羞捂脸', loop: false },
+  { id: PET_ROLES.drag, loop: true },
+  { id: '原地踏步', loop: true },
+  { id: '吃橘子', loop: false },
+  { id: '挥手打招呼', loop: false },
+  { id: '原地小憩', loop: true },
+  { id: '泡温泉', loop: true },
+])
+
 /** 仓库主页（更新提示与"查看更新"链接的唯一来源）。 */
 export const REPO_URL = 'https://github.com/WWFZS/dsh-plugin-startup-animation'
 
@@ -369,6 +405,14 @@ export const DEFAULT_CONFIG = Object.freeze({
   skipLabel: '',
   /** 声音被浏览器拦下时开关的文案；'' = 运行时按语言选择。 */
   soundLabel: '',
+  // ── 桌面宠物（浮在 DSH 界面上的透明小动物）──
+  /** 是否显示宠物。默认关：装上新版不该突然冒出一只动物。 */
+  petEnabled: false,
+  /** 宠物显示宽度（px）。高度按素材 3:4 自动算。 */
+  petSize: 176,
+  /** 宠物位置：0–100 的百分比，100 = 贴右/贴下。见 client.js 的定位算法。 */
+  petX: 100,
+  petY: 100,
 })
 
 /** 素材扩展名 → 运行时呈现方式。不支持的扩展名只让该素材降级，不影响动画本身。 */
@@ -1149,6 +1193,9 @@ export function scanLibrary(packageRoot, deleted = [], homeDir) {
   const byName = (a, b) => a.name.localeCompare(b.name)
   for (const dir of dirs) {
     if (!dir.isDirectory()) continue
+    // 宠物动画不是启动素材：它们只有三个固定文件，由宠物浮层按 PET_CLIPS 取用。
+    // 列进素材库只会让用户在"MP4"分类里点到一个 3:4 的小动物。
+    if (dir.name === PET_DIR_NAME) continue
     const catDir = path.join(rootDir, dir.name)
     let files
     try {
@@ -1678,6 +1725,70 @@ export function removeUploadedFile(homeDir, value) {
   return abs
 }
 
+/**
+ * 宠物可用的动作清单：**扫目录**，不是白名单。
+ *
+ * 往 `builtin/宠物/` 丢一个 `睡觉.webm`，设置页的动作列表里就会多一条「睡觉」，
+ * 不需要改代码、不需要重启（每次 manage 都重新扫）。
+ *
+ * 三个约定：
+ *   - 文件名（去扩展名）就是动作 id，也是界面上显示的名字；
+ *   - `PET_CLIPS` 里声明过的动作按声明顺序排在前面，其余按文件名排；
+ *   - 没声明的动作默认循环播放，`loop:false` 的（点击回应）播完回待机。
+ *
+ * 读不到目录就返回空数组 —— 宠物不出现，比整个设置页报错好。
+ *
+ * @param {string} packageRoot 包根。
+ * @returns {Array<{ id: string, name: string, file: string, loop: boolean }>} 可播放的动作。
+ */
+export function listPetClips(packageRoot) {
+  const dir = path.join(packageRoot, BUILTIN_DIR_NAME, PET_DIR_NAME)
+  /** @type {import('node:fs').Dirent[]} */
+  let entries
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const declared = new Map(PET_CLIPS.map((clip, index) => [clip.id, { index, loop: clip.loop !== false }]))
+  /** @type {Array<{ id: string, name: string, file: string, loop: boolean, rank: number }>} */
+  const clips = []
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    const name = entry.name
+    if (path.extname(name).toLowerCase() !== '.webm') continue
+    let stat
+    try {
+      stat = fs.statSync(path.join(dir, name))
+    } catch {
+      continue
+    }
+    if (!stat.isFile() || stat.size <= 0) continue
+    const id = name.slice(0, -'.webm'.length)
+    if (id === '') continue
+    const known = declared.get(id)
+    clips.push({
+      id,
+      name: id,
+      file: `${BUILTIN_DIR_NAME}/${PET_DIR_NAME}/${name}`,
+      loop: known === undefined ? true : known.loop,
+      rank: known === undefined ? PET_CLIPS.length : known.index,
+    })
+  }
+  clips.sort((a, b) => (a.rank === b.rank ? a.id.localeCompare(b.id, 'zh') : a.rank - b.rank))
+  return clips.map(({ rank, ...clip }) => clip)
+}
+
+/**
+ * 从动作清单里取一个语义角色实际指向的动作 id。
+ * @param {Array<{ id: string }>} clips 动作清单。
+ * @param {string} wanted 期望的动作 id。
+ * @returns {string} 存在则返回它，否则 `''`（客户端据此降级）。
+ */
+function pickClip(clips, wanted) {
+  return clips.some((clip) => clip.id === wanted) ? wanted : ''
+}
+
 /**
  * 当前管理状态（界面上"上传/开关/恢复/素材库"的回显）。
  * @param {{ packageRoot: string, homeDir?: string, route: string }} options 位置。
@@ -1686,6 +1797,8 @@ export function removeUploadedFile(homeDir, value) {
 export function manageStatus(options) {
   // 一次 loadConfig 就够：`raw` 与 `sources` 已经在里面读好了。
   const { client, assetPath, warnings, raw } = loadConfig(options)
+  // 动作清单只扫一次：pet 里三处语义 + 列表都从它来（扫目录要 stat 每个文件）。
+  const petClips = listPetClips(options.packageRoot)
   const fileRaw = typeof raw.file === 'string' ? raw.file : ''
   const audioFileRaw = typeof raw.audioFile === 'string' ? raw.audioFile : ''
   const deleted = Array.isArray(raw.deleted)
@@ -1724,6 +1837,25 @@ export function manageStatus(options) {
     /** 素材库：内置 + 上传合并，上传按扩展名自动归入 MP4/图片/音频分类；已排除 tombstone。 */
     library: scanLibrary(options.packageRoot, deleted, options.homeDir),
     limitBytes: MEDIA_LIMIT_BYTES,
+    /**
+     * 桌面宠物域：开关 / 大小 / 位置 / 动作列表。
+     *
+     * `clips[].file` 是包内相对路径，客户端拼成 `ASSET?path=…` 取流 —— 复用既有的
+     * 素材路由（它有 Range、ETag、逃逸防护），不为宠物再开一条发文件的通道。
+     *
+     * `idle` / `click` / `drag` 是**语义**：哪个动作当待机、点击时播哪个、拖动时播哪个。
+     * 由宿主决定、客户端照用，这样改文件名不用动前端。
+     */
+    pet: {
+      enabled: raw.petEnabled === true,
+      size: clampNumber(raw.petSize, DEFAULT_CONFIG.petSize, 100, 320),
+      x: clampNumber(raw.petX, DEFAULT_CONFIG.petX, 0, 100),
+      y: clampNumber(raw.petY, DEFAULT_CONFIG.petY, 0, 100),
+      idle: pickClip(petClips, PET_ROLES.idle) || (petClips[0] === undefined ? '' : petClips[0].id),
+      click: pickClip(petClips, PET_ROLES.click),
+      drag: pickClip(petClips, PET_ROLES.drag),
+      clips: petClips,
+    },
     /**
      * 开机动画运行时的完整配置（boot.js 每次页面加载实时读取它 —— 桌面注入表是宿主
      * 启动时的一次性快照，配置改动必须走实时通道才能"刷新即生效"）。
@@ -2246,8 +2378,27 @@ export function apply(ctx) {
                     }
                     patch.durationSec = clampDurationSec(body.durationSec)
                   }
+                  // ── 宠物域：开关 / 大小 / 位置 ──
+                  // 大小与位置照旧"服务端夹取不给商用"：越界的值就地夹好，不报错 ——
+                  // 拖到屏幕边缘时客户端算出的百分比偶尔会是 100.4 这种数。
+                  if (typeof body.petEnabled === 'boolean') patch.petEnabled = body.petEnabled
+                  if (body.petSize !== undefined) {
+                    if (typeof body.petSize !== 'number' || !Number.isFinite(body.petSize)) {
+                      reply(res, 400, { ok: false, error: '宠物大小必须是 100–320 的数字（px）' })
+                      return
+                    }
+                    patch.petSize = clampNumber(body.petSize, DEFAULT_CONFIG.petSize, 100, 320)
+                  }
+                  for (const key of ['petX', 'petY']) {
+                    if (body[key] === undefined) continue
+                    if (typeof body[key] !== 'number' || !Number.isFinite(body[key])) {
+                      reply(res, 400, { ok: false, error: '宠物位置必须是 0–100 的数字' })
+                      return
+                    }
+                    patch[key] = clampNumber(body[key], DEFAULT_CONFIG[key], 0, 100)
+                  }
                   if (Object.keys(patch).length === 0) {
-                    reply(res, 400, { ok: false, error: 'expected "enabled", "sound", "audioEnabled", "audioVolume", "durationSec", "use", "useAudio" or "forget"' })
+                    reply(res, 400, { ok: false, error: 'expected "enabled", "sound", "audioEnabled", "audioVolume", "durationSec", "petEnabled", "petSize", "petX", "petY", "use", "useAudio" or "forget"' })
                     return
                   }
                   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-startup-animation",
-  "version": "1.12.7",
+  "version": "1.13.0",
   "type": "module",
   "description": "Animated full-screen startup screen shown while DeepSeek Harness boots — click to skip. Ships a built-in MP4/wallpaper/audio library and accepts your own files. 开机动画 / 启动动画：启动 Harness 时显示全屏动画，随包内置视频、壁纸与开机音频，也可以用自己的素材。",
   "license": "MIT",
@@ -56,7 +56,8 @@
     "screenshots.json",
     "LICENSE",
     "builtin/图片/**/*",
-    "builtin/音频/**/*"
+    "builtin/音频/**/*",
+    "builtin/宠物/**/*"
   ],
   "scripts": {
     "test": "node selftest.mjs && node tools/boot-runtime.mjs && node tools/client-test.mjs && node lib/self-manage-test.mjs && node lib/e2e-uninstall.mjs && node tools/boot-css-test.mjs && node tools/host-smoke.mjs",

package/screenshots.json

@@ -1,5 +1,4 @@
 [
-  "docs/avatar.png",
-  "docs/library.jpg",
+  "docs/library-videos.jpg",
   "docs/library-wallpapers.jpg"
 ]