dsh-folia 4.0.8 → 4.3.0

package/lib/client.js

@@ -17180,6 +17180,596 @@ window.__ModuleLoader__.load({
 				  return React.createElement(BootTabPanel, null);
 				}
 
+				// ── 内联模块：src/panel-tabs-pets.js —— 「桌宠」页签：站点清单/安装/使用/卸载/开关 — 渲染由 pet-layer.js 负责，这里只管动作（构建期注入；勿手改本段）──
+				/**
+				 * panel-tabs-pets.js — 「桌宠」页签：站点清单 / 安装 / 使用 / 卸载 / 开关 / 缩放。
+				 *
+				 * 与「开机动画」页签同构（fetch → busy → note → 卡片列表），差别只有一处：
+				 * 开机动画的播放不在前端（启动那一刻应用还没挂载），而桌宠**就活在前端** ——
+				 * 这里的每个动作最终都落到宿主 `/folia/pets/*`，渲染由 pet-layer.js 负责。
+				 */
+
+				const PET_STYLE = {
+				  row: { display: "flex", alignItems: "center", gap: "10px", flexWrap: "wrap" },
+				  card: {
+				    display: "flex", flexDirection: "column", gap: "8px", padding: "12px",
+				    borderRadius: "10px", border: "1px solid rgba(255,255,255,0.14)",
+				    background: "rgba(255,255,255,0.04)", minWidth: "220px", flex: "1 1 220px",
+				  },
+				  title: { fontSize: "13px", fontWeight: 600 },
+				  meta: { fontSize: "11px", opacity: 0.72 },
+				  grid: { display: "flex", gap: "10px", flexWrap: "wrap", marginTop: "10px" },
+				};
+
+				function petFmtBytes(n) {
+				  const v = Number(n) || 0;
+				  if (!v) return "";
+				  if (v < 1024 * 1024) return Math.round(v / 1024) + " KB";
+				  return (v / 1048576).toFixed(1) + " MB";
+				}
+
+				function PetsTabPanel() {
+				  const [state, setState] = React.useState(null);
+				  const [busy, setBusy] = React.useState("");
+				  const [note, setNote] = React.useState(null);
+
+				  const load = React.useCallback(async (force) => {
+				    try {
+				      const resp = await apiJson("/pets/list" + (force ? "?refresh=1" : ""), { parse: "always" });
+				      const doc = (resp && resp.data) || null;
+				      if (resp && resp.ok && doc && doc.ok) setState(doc);
+				      else setNote({ ok: false, text: weT("读取失败：") + ((resp && resp.error) || "unknown") });
+				    } catch (e) {
+				      setNote({ ok: false, text: weT("请求失败：") + ((e && e.message) || weT("网络错误")) });
+				    }
+				  }, []);
+
+				  React.useEffect(() => { load(false); }, [load]);
+
+				  const act = async (kind, payload, label) => {
+				    setBusy(kind + ":" + (payload.id || ""));
+				    setNote(null);
+				    try {
+				      const resp = await apiPostJson("/pets/" + kind, payload || {}, { parse: "always" });
+				      const r = (resp && resp.data) || null;
+				      if (resp && resp.ok && r && r.ok) {
+				        if (kind === "install") setNote({ ok: true, text: weT("已安装并启用：") + (label || "") });
+				        if (kind === "remove") setNote({ ok: true, text: weT("已卸载：") + (label || "") });
+				        if (kind === "config") setNote({ ok: true, text: weT("已保存") });
+				        await load(true);
+				      } else {
+				        const code = (r && r.error) || "failed";
+				        setNote({ ok: false, text: weT("操作失败：") + code });
+				      }
+				    } catch (e) {
+				      setNote({ ok: false, text: weT("请求失败：") + ((e && e.message) || weT("网络错误")) });
+				    } finally {
+				      setBusy("");
+				    }
+				  };
+
+				  const pets = (state && state.pets) || [];
+				  const site = (state && state.site) || [];
+				  const cfg = (state && state.config) || { enabled: false, petId: "", scale: 1 };
+				  const installedIds = new Set(pets.map((p) => p.dirId));
+
+				  if (!state) {
+				    return React.createElement("div", { className: "we-picker__section" },
+				      React.createElement("div", { className: "we-picker__hint" }, weT("正在读取桌宠…")));
+				  }
+
+				  const children = [];
+
+				  children.push(React.createElement("div", { className: "we-picker__section-head", key: "head" },
+				    React.createElement("span", { className: "we-picker__section-label" },
+				      weT("🐾 桌宠") + (pets.length ? "  ·  " + pets.length : "")),
+				    React.createElement("button", {
+				      type: "button", className: "we-picker__btn", style: { marginLeft: "auto" },
+				      disabled: Boolean(busy), onClick: () => load(true),
+				    }, weT("刷新")),
+				  ));
+
+				  children.push(React.createElement("div", { key: "hint", className: "we-picker__hint", style: { margin: "6px 0 10px" } },
+				    weT("桌宠由本插件自己绘制（雪碧图逐帧），不依赖其它宠物插件。它会跟着模型状态换动作：干活时换成工作行、干完变完成、出错变失败；安装后出现在右下角，可拖动，点一下会挥手并出声。")));
+
+				  children.push(React.createElement("div", { key: "opts", style: { ...PET_STYLE.row, margin: "2px 0 8px" } },
+				    React.createElement("label", { style: { display: "flex", gap: "6px", alignItems: "center", fontSize: "12px" } },
+				      React.createElement("input", {
+				        type: "checkbox",
+				        checked: Boolean(cfg.enabled),
+				        disabled: Boolean(busy) || !pets.length,
+				        onChange: (e) => act("config", { enabled: e.target.checked }, ""),
+				      }),
+				      weT("显示桌宠"),
+				    ),
+				    React.createElement("label", { style: { display: "flex", gap: "6px", alignItems: "center", fontSize: "12px" } },
+				      React.createElement("input", {
+				        type: "checkbox",
+				        checked: Boolean(cfg.sound),
+				        disabled: Boolean(busy),
+				        onChange: (e) => act("config", { sound: e.target.checked }, ""),
+				      }),
+				      weT("声音"),
+				    ),
+				    React.createElement("label", { style: { display: "flex", gap: "4px", alignItems: "center", fontSize: "12px" } },
+				      weT("音量"),
+				      React.createElement("select", {
+				        className: "we-picker__playlist-select",
+				        value: String(cfg.volume == null ? 0.6 : cfg.volume),
+				        disabled: Boolean(busy) || !cfg.sound,
+				        onChange: (e) => act("config", { volume: Number(e.target.value) }, ""),
+				      },
+				      [[0.2, "20%"], [0.4, "40%"], [0.6, "60%"], [0.8, "80%"], [1, "100%"]].map(([v, lb]) =>
+				        React.createElement("option", { key: String(v), value: String(v) }, lb)),
+				      ),
+				    ),
+				    React.createElement("button", {
+				      type: "button", className: "we-picker__btn", disabled: Boolean(busy),
+				      title: weT("把桌宠挪回右下角"),
+				      onClick: () => { try { localStorage.removeItem("wePetPos"); } catch { /* ignore */ } setNote({ ok: true, text: weT("位置已复位（下一次出现回到右下角）") }); },
+				    }, weT("复位位置")),
+				    React.createElement("label", { style: { display: "flex", gap: "4px", alignItems: "center", fontSize: "12px" } },
+				      weT("大小"),
+				      React.createElement("select", {
+				        className: "we-picker__playlist-select",
+				        value: String(cfg.scale || 1),
+				        disabled: Boolean(busy),
+				        onChange: (e) => act("config", { scale: Number(e.target.value) }, ""),
+				      },
+				      [[0.6, "60%"], [0.8, "80%"], [1, "100%"], [1.3, "130%"], [1.6, "160%"]].map(([v, t]) =>
+				        React.createElement("option", { key: String(v), value: String(v) }, t)),
+				      ),
+				    ),
+				  ));
+
+				  if (note) {
+				    children.push(React.createElement("div", {
+				      key: "note",
+				      className: "we-picker__hint",
+				      style: { color: note.ok ? "rgba(120,220,150,0.95)" : "rgba(255,140,140,0.95)", margin: "2px 0 8px" },
+				    }, note.text));
+				  }
+
+				  const btn = (text, onClick, disabled) => React.createElement("button", {
+				    type: "button", className: "we-picker__btn", disabled: Boolean(disabled),
+				    style: { flex: "1 1 auto" }, onClick,
+				  }, text);
+
+				  // 已装：换一只 / 卸载
+				  children.push(React.createElement("div", { key: "installed", style: PET_STYLE.grid },
+				    pets.length
+				      ? pets.map((p) => {
+				        const isActive = cfg.petId === p.dirId || cfg.petId === p.id;
+				        const key = "inst:" + p.dirId;
+				        const actions = [];
+				        actions.push(btn(isActive ? weT("使用中") : weT("使用"), () => act("config", { enabled: true, petId: p.dirId }, p.name), isActive || Boolean(busy)));
+				        actions.push(btn(weT("卸载"), () => act("remove", { id: p.dirId }, p.name), Boolean(busy)));
+				        return React.createElement("div", { key, style: PET_STYLE.card },
+				          React.createElement("img", {
+				            src: p.sheet, alt: "", loading: "lazy", decoding: "async",
+				            style: { width: "100%", maxHeight: "96px", objectFit: "contain", background: "rgba(0,0,0,0.25)", borderRadius: "6px" },
+				            onError: (e) => { e.target.style.display = "none"; },
+				          }),
+				          React.createElement("div", { style: PET_STYLE.title }, p.name),
+				          React.createElement("div", { style: PET_STYLE.meta },
+				            (p.columns || 8) + weT(" 列 · ") + (p.cell ? p.cell.width + "×" + p.cell.height : "")),
+				          React.createElement("div", { style: PET_STYLE.row }, actions),
+				        );
+				      })
+				      : React.createElement("div", { className: "we-picker__hint" }, weT("还没有安装任何桌宠 —— 从下面的站点清单里挑一只。")),
+				  ));
+
+				  // 站点：未装的可安装
+				  const available = site.filter((s) => !installedIds.has(s.id));
+				  children.push(React.createElement("div", { key: "siteHead", className: "we-picker__section-head", style: { marginTop: "14px" } },
+				    React.createElement("span", { className: "we-picker__section-label" },
+				      weT("站点桌宠") + (site.length ? "  ·  " + site.length : "")),
+				    state.siteError
+				      ? React.createElement("span", { className: "we-picker__hint", style: { marginLeft: "auto" } }, weT("站点不可达"))
+				      : null,
+				  ));
+
+				  if (available.length) {
+				    children.push(React.createElement("div", { key: "site", style: PET_STYLE.grid },
+				      available.map((s) => {
+				        const isBusy = busy === "install:" + s.id;
+				        return React.createElement("div", { key: "site:" + s.id, style: PET_STYLE.card },
+				          s.cover
+				            ? React.createElement("img", {
+				              src: s.cover, alt: "", loading: "lazy", decoding: "async",
+				              style: { width: "100%", maxHeight: "96px", objectFit: "cover", borderRadius: "6px" },
+				              onError: (e) => { e.target.style.display = "none"; },
+				            })
+				            : null,
+				          React.createElement("div", { style: PET_STYLE.title }, s.title || s.id),
+				          React.createElement("div", { style: PET_STYLE.meta }, petFmtBytes(s.bytes)),
+				          React.createElement("div", { style: PET_STYLE.row },
+				            btn(isBusy ? weT("安装中…") : weT("安装"), () => act("install", { id: s.id }, s.title || s.id), Boolean(busy))),
+				        );
+				      }),
+				    ));
+				  } else if (!site.length) {
+				    children.push(React.createElement("div", { key: "siteEmpty", className: "we-picker__hint", style: { marginTop: "6px" } },
+				      weT("站点上还没有桌宠。")));
+				  }
+
+				  return React.createElement("div", { className: "we-picker__section" }, children);
+				}
+
+				/** 页签组装点调用它。 */
+				function renderPetsTab() {
+				  return React.createElement(PetsTabPanel, null);
+				}
+
+				// ── 内联模块：src/pet-layer.js —— 桌宠渲染层：canvas 逐帧绘 sprite2d 雪碧图 + 拖动 + 状态机（自渲染，不依赖第三方宠物插件）（构建期注入；勿手改本段）──
+				/**
+				 * pet-layer.js — 桌宠**渲染层**（自己画，不依赖任何第三方宠物插件）。
+				 *
+				 * 形态：`<body>` 下的一个 fixed 容器 + 一张 canvas，用 sprite2d 雪碧图逐帧绘制。
+				 *
+				 * 契约（与宿主 `/folia/pets/list` 一致）：
+				 *   pets[i] = { id, dirId, name, renderer, cell:{width,height}, columns, frames:number[9],
+				 *               tracks:{ <轨道名>: { durations:number[] } }, sheet:'/folia/pets/sheet?v=<dirId>' }
+				 *
+				 * 行序（9 行，dsh-pet 的 contract，缺轨道时回落 idle）：
+				 *   0 idle · 1 右跑 · 2 左跑 · 3 挥手 · 4 跳 · 5 失败 · 6 等待 · 7 工作 · 8 完成
+				 *
+				 * 为什么整层是"命令式 DOM + rAF"而不是 React：它每秒重绘几十次，进 React 只会让
+				 * 每次 setState 触发整棵树协调；这里只碰一个 canvas 的像素，与面板渲染互不干扰。
+				 */
+
+				const PET_LAYER_ID = "we-pet-layer";
+				const PET_ROW = { idle: 0, runRight: 1, runLeft: 2, wave: 3, jump: 4, fail: 5, wait: 6, work: 7, done: 8 };
+				const PET_DEFAULT_FRAME_MS = 120;
+				/**
+				 * 活动检测：DSH 的客户端 `ctx` 只暴露 effect/get/slots/surface，没有会话事件，
+				 * 所以"模型在不在干活"只能从**页面本身**读。两条独立信号，任一命中即认为在工作：
+				 *   ① DOM 特征：选择器（默认覆盖常见的 streaming / 生成中 标记）
+				 *   ② 文本特征：屏幕上出现"正在生成 / 思考中 / Stop generating"这类字眼
+				 * 两条都读不到时**安静地停在 idle** —— 宁可不动，也不要让宠物乱跳。
+				 */
+				const PET_ACTIVITY_SELECTORS = [
+				  '[data-dsh-streaming]', '[data-streaming="true"]', '.ds-streaming',
+				  '[class*="streaming"]', '[class*="isGenerating"]', '[aria-busy="true"]',
+				];
+				const PET_ACTIVITY_TEXTS = ['正在生成', '思考中', '停止生成', 'Stop generating', 'Thinking'];
+				/** 检测节流（毫秒）：一次 body 扫描比一次布局还便宜，但没必要每帧跑。 */
+				const PET_ACTIVITY_POLL_MS = 500;
+				/** 光标静止后多久切回 idle（毫秒）。 */
+				const PET_WAVE_IDLE_MS = 9000;
+
+				/**
+				 * 声音：包内 `sounds/<事件>.ogg|mp3|wav` 优先（manifest.sounds 显式声明），
+				 * 没有就用 Web Audio 合成 —— 一只宠物没声音比"声音是版权素材"糟得多。
+				 * 全部失败都静默：声音是可选项，不该有能力打断渲染。
+				 */
+				function petVoice(ctxWindow, sounds, cfg) {
+				  const enabled = Boolean(cfg && cfg.sound);
+				  const volume = Math.max(0, Math.min(1, Number(cfg && cfg.volume) || 0));
+				  let audioCtx = null;
+				  const cache = new Map();
+
+				  function ensureCtx() {
+				    if (audioCtx || typeof ctxWindow.AudioContext !== 'function') return audioCtx;
+				    try { audioCtx = new ctxWindow.AudioContext(); } catch { audioCtx = null; }
+				    return audioCtx;
+				  }
+
+				  /** 合成提示音：不同事件不同音高与波形，短、克制。 */
+				  function synth(kind) {
+				    const ac = ensureCtx();
+				    if (!ac) return;
+				    const spec = kind === "done" ? { f: 880, d: 0.09, w: "sine" }
+				      : kind === "fail" ? { f: 220, d: 0.16, w: "sawtooth" }
+				      : { f: 620, d: 0.08, w: "triangle" };
+				    try {
+				      const osc = ac.createOscillator();
+				      const gain = ac.createGain();
+				      osc.type = spec.w;
+				      osc.frequency.value = spec.f;
+				      gain.gain.value = 0.0001;
+				      osc.connect(gain);
+				      gain.connect(ac.destination);
+				      const now = ac.currentTime;
+				      gain.gain.exponentialRampToValueAtTime(Math.max(0.0001, volume * 0.25), now + 0.01);
+				      gain.gain.exponentialRampToValueAtTime(0.0001, now + spec.d);
+				      osc.start(now);
+				      osc.stop(now + spec.d + 0.02);
+				    } catch { /* 合成失败就算了 */ }
+				  }
+
+				  function file(kind) {
+				    const url = sounds && sounds[kind];
+				    if (!url) return null;
+				    let el = cache.get(kind);
+				    if (!el) {
+				      try { el = new ctxWindow.Audio(apiUrl(url)); } catch { return null; }
+				      el.preload = "auto";
+				      cache.set(kind, el);
+				    }
+				    return el;
+				  }
+
+				  return {
+				    get enabled() { return enabled; },
+				    play(kind) {
+				      if (!enabled || volume <= 0) return;
+				      const el = file(kind);
+				      if (el) {
+				        try { el.currentTime = 0; el.volume = volume; const p = el.play(); if (p && p.catch) p.catch(() => synth(kind)); return; } catch { /* 落回合成 */ }
+				      }
+				      synth(kind);
+				    },
+				    destroy() {
+				      cache.clear();
+				      try { if (audioCtx && typeof audioCtx.close === "function") audioCtx.close(); } catch { /* ignore */ }
+				      audioCtx = null;
+				    },
+				  };
+				}
+
+				/** 页面里现在像不像"模型在干活"。任何异常都当 false。 */
+				function petActivityProbe() {
+				  try {
+				    if (typeof document === 'undefined' || !document.body) return false;
+				    for (const sel of PET_ACTIVITY_SELECTORS) {
+				      if (document.querySelector(sel)) return true;
+				    }
+				    const text = document.body.innerText || "";
+				    for (const marker of PET_ACTIVITY_TEXTS) {
+				      if (text.indexOf(marker) !== -1) return true;
+				    }
+				  } catch { /* ignore */ }
+				  return false;
+				}
+
+				/**
+				 * 桌宠实例：一只宠物一条生命周期（换宠物 = 销毁重来）。
+				 * 不导出（构建期内联进同一作用域），只由 mountPetLayer 使用。
+				 */
+				function createPetLayer(layerEl, canvas, pet, scale, cfg) {
+				  const ctx = canvas.getContext("2d");
+				  const img = new Image();
+				  let frame = 0;
+				  let row = PET_ROW.idle;
+				  let acc = 0;
+				  let last = 0;
+				  let raf = 0;
+				  let dead = false;
+				  let idleSince = 0;
+				  let dragging = null;
+				  let ready = false;
+				  const voice = petVoice(typeof window !== "undefined" ? window : {}, pet.sounds, cfg || {});
+				  let activity = false;
+				  let activityTimer = null;
+				  /** 一次性动作（done/fail）播完自动回 idle 的时间戳。 */
+				  let holdUntil = 0;
+
+				  const cw = Math.max(1, Number(pet.cell && pet.cell.width) || 192);
+				  const ch = Math.max(1, Number(pet.cell && pet.cell.height) || 208);
+				  const cols = Math.max(1, Number(pet.columns) || 8);
+				  const frames = Array.isArray(pet.frames) && pet.frames.length ? pet.frames : new Array(9).fill(cols);
+
+				  function rowFrames(r) {
+				    const n = Number(frames[r]);
+				    return Number.isFinite(n) && n > 0 ? Math.min(cols, n) : cols;
+				  }
+				  function frameMs(r, f) {
+				    const t = pet.tracks && pet.tracks[Object.keys(PET_ROW)[r] === undefined ? "" : Object.keys(PET_ROW)[r]];
+				    const d = t && Array.isArray(t.durations) ? t.durations[f] : null;
+				    return Number.isFinite(Number(d)) && Number(d) > 0 ? Number(d) : PET_DEFAULT_FRAME_MS;
+				  }
+
+				  function resize() {
+				    const w = Math.round(cw * scale);
+				    const h = Math.round(ch * scale);
+				    const dpr = Math.min(3, Math.max(1, (typeof window !== "undefined" && window.devicePixelRatio) || 1));
+				    canvas.width = Math.round(w * dpr);
+				    canvas.height = Math.round(h * dpr);
+				    canvas.style.width = w + "px";
+				    canvas.style.height = h + "px";
+				    if (canvas.getContext) {
+				      const c2 = canvas.getContext("2d");
+				      if (c2 && c2.setTransform) c2.setTransform(dpr, 0, 0, dpr, 0, 0);
+				    }
+				  }
+
+				  function draw() {
+				    if (!ready || dead) return;
+				    const n = rowFrames(row);
+				    if (frame >= n) frame = 0;
+				    const sx = frame * cw;
+				    const sy = row * ch;
+				    try {
+				      ctx.clearRect(0, 0, cw * scale, ch * scale);
+				      ctx.drawImage(img, sx, sy, cw, ch, 0, 0, cw * scale, ch * scale);
+				    } catch { /* 贴图还没解码完：下一帧再画 */ }
+				  }
+
+				  function tick(now) {
+				    if (dead) return;
+				    if (!last) last = now;
+				    acc += now - last;
+				    last = now;
+				    // 活动状态变化时先切行（work/done/fail 优先于 idle/wave）。
+				    if (activityTimer === null && typeof setInterval === "function") {
+				      activityTimer = setInterval(() => {
+				        const nowActive = petActivityProbe();
+				        if (nowActive === activity && now < holdUntil) return;
+				        activity = nowActive;
+				        if (activity) {
+				          holdUntil = 0;
+				          if (row !== PET_ROW.work) setRow(PET_ROW.work);
+				        } else if (row === PET_ROW.work) {
+				          // 干完活 → 完成行一小会儿，再回 idle（"被看见"的反馈）
+				          setRow(PET_ROW.done);
+				          holdUntil = Date.now() + 1600;
+				          voice.play("done");
+				        }
+				      }, PET_ACTIVITY_POLL_MS);
+				    }
+				    if (holdUntil && now >= holdUntil) { holdUntil = 0; setRow(PET_ROW.idle); }
+				    const ms = frameMs(row, frame);
+				    if (acc >= ms) {
+				      acc = 0;
+				      frame += 1;
+				      if (frame >= rowFrames(row)) {
+				        frame = 0;
+				        // 一次性动作（挥手 / 跳）播完回 idle
+				        if (row === PET_ROW.wave || row === PET_ROW.jump) row = PET_ROW.idle;
+				        // done / fail 由 holdUntil 计时收尾，不在这里回 idle（否则刚出现的反馈会被吞掉）。
+				      }
+				    }
+				    draw();
+				    raf = (typeof requestAnimationFrame === "function")
+				      ? requestAnimationFrame(tick)
+				      : setTimeout(() => tick(Date.now()), 60);
+				  }
+
+				  function setRow(next) {
+				    if (row === next) return;
+				    row = next;
+				    frame = 0;
+				    acc = 0;
+				  }
+
+				  function onPointerDown(e) {
+				    if (!layerEl) return;
+				    dragging = {
+				      dx: e.clientX - layerEl.offsetLeft,
+				      dy: e.clientY - layerEl.offsetTop,
+				      moved: false,
+				    };
+				    try { canvas.setPointerCapture && canvas.setPointerCapture(e.pointerId); } catch { /* ignore */ }
+				    e.preventDefault();
+				  }
+				  function onPointerMove(e) {
+				    if (!dragging) return;
+				    const x = Math.max(0, Math.min((window.innerWidth || 1920) - layerEl.offsetWidth, e.clientX - dragging.dx));
+				    const y = Math.max(0, Math.min((window.innerHeight || 1080) - layerEl.offsetHeight, e.clientY - dragging.dy));
+				    layerEl.style.left = x + "px";
+				    layerEl.style.top = y + "px";
+				    layerEl.style.right = "auto";
+				    layerEl.style.bottom = "auto";
+				    dragging.moved = true;
+				  }
+				  function onPointerUp() {
+				    if (!dragging) return;
+				    const moved = dragging.moved;
+				    dragging = null;
+				    if (!moved) {
+				      // 单击 = 挥手（给用户一个"它有反应"的反馈），之后自动回 idle
+				      setRow(PET_ROW.wave);
+				      voice.play("wave");
+				    } else {
+				      try { localStorage.setItem("wePetPos", JSON.stringify({ left: layerEl.style.left, top: layerEl.style.top })); } catch { /* ignore */ }
+				    }
+				  }
+
+				  img.onload = () => { ready = true; resize(); draw(); };
+				  img.onerror = () => { destroy(); };
+				  img.src = apiUrl(pet.sheet || "/pets/sheet?v=" + encodeURIComponent(pet.dirId || pet.id));
+
+				  canvas.addEventListener("pointerdown", onPointerDown);
+				  if (typeof window !== "undefined") {
+				    window.addEventListener("pointermove", onPointerMove);
+				    window.addEventListener("pointerup", onPointerUp);
+				  }
+				  idleSince = Date.now();
+				  raf = (typeof requestAnimationFrame === "function") ? requestAnimationFrame(tick) : setTimeout(() => tick(Date.now()), 60);
+
+				  function destroy() {
+				    dead = true;
+				    if (typeof clearInterval === "function" && activityTimer !== null) clearInterval(activityTimer);
+				    activityTimer = null;
+				    try { voice.destroy(); } catch { /* ignore */ }
+				    if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(raf); else clearTimeout(raf);
+				    canvas.removeEventListener("pointerdown", onPointerDown);
+				    if (typeof window !== "undefined") {
+				      window.removeEventListener("pointermove", onPointerMove);
+				      window.removeEventListener("pointerup", onPointerUp);
+				    }
+				  }
+
+				  return {
+				    destroy, setRow, resize,
+				    /** 外部事件注入（面板操作失败等）：一次性播放失败行并出声。 */
+				    fail() { setRow(PET_ROW.fail); holdUntil = Date.now() + 1600; voice.play("fail"); },
+				    cheer() { setRow(PET_ROW.done); holdUntil = Date.now() + 1600; voice.play("done"); },
+				    get row() { return row; },
+				  };
+				}
+
+				/**
+				 * 挂载桌宠层。返回卸载函数（无宠物 / 未启用时返回 null）。
+				 *
+				 * 它自己拉 `/folia/pets/list`（配置 + 已装宠物），所以**不依赖面板是否打开过** ——
+				 * 冷启动就能出宠物。
+				 */
+				function mountPetLayer() {
+				  if (typeof document === "undefined" || !document.body) return null;
+				  let disposed = false;
+				  let instance = null;
+				  let layerEl = null;
+
+				  function teardownDom() {
+				    if (instance) { try { instance.destroy(); } catch { /* ignore */ } instance = null; }
+				    if (layerEl && layerEl.parentNode) layerEl.parentNode.removeChild(layerEl);
+				    layerEl = null;
+				  }
+
+				  async function sync() {
+				    let doc = null;
+				    try {
+				      const resp = await apiJson("/pets/list", { parse: "always" });
+				      doc = (resp && resp.data) || null;
+				    } catch { doc = null; }
+				    if (disposed) return;
+				    const cfg = (doc && doc.config) || null;
+				    const pets = (doc && doc.pets) || [];
+				    const pet = cfg && cfg.petId ? pets.find((p) => p.dirId === cfg.petId || p.id === cfg.petId) : null;
+				    if (!cfg || !cfg.enabled || !pet) { teardownDom(); return; }
+
+				    const scale = Number(cfg.scale) > 0 ? Number(cfg.scale) : 1;
+				    if (layerEl) { layerEl.style.display = ""; if (instance) instance.resize(); return; }
+
+				    layerEl = document.createElement("div");
+				    layerEl.id = PET_LAYER_ID;
+				    layerEl.style.cssText = [
+				      "position:fixed", "right:24px", "bottom:16px", "z-index:2147482000",
+				      "cursor:grab", "user-select:none", "touch-action:none",
+				      "filter:drop-shadow(0 6px 14px rgba(0,0,0,0.35))",
+				    ].join(";");
+				    try {
+				      const saved = JSON.parse(localStorage.getItem("wePetPos") || "null");
+				      if (saved && saved.left && saved.top) {
+				        layerEl.style.left = saved.left;
+				        layerEl.style.top = saved.top;
+				        layerEl.style.right = "auto";
+				        layerEl.style.bottom = "auto";
+				      }
+				    } catch { /* 用默认位置 */ }
+				    const canvas = document.createElement("canvas");
+				    layerEl.appendChild(canvas);
+				    document.body.appendChild(layerEl);
+				    instance = createPetLayer(layerEl, canvas, pet, scale, cfg);
+				  }
+
+				  sync();
+				  // 配置变化（面板里换宠物/开关）不需要重启：轻量轮询即可，代价是一次本地 HTTP。
+				  // ⚠️ 定时器要 feature-detect：宿主在 smoke / 单测沙箱里没有 timers，直接调会 ReferenceError，
+				  //    而那一抛会把整个 apply 打成失败（实测：smoke 第 1 步就红）。
+				  const timer = typeof setInterval === 'function'
+				    ? setInterval(() => { if (!disposed) sync(); }, 4000)
+				    : null;
+
+				  return () => {
+				    disposed = true;
+				    if (typeof clearInterval === 'function' && timer !== null) clearInterval(timer);
+				    teardownDom();
+				  };
+				}
+
 				// ── 内联模块：src/quick-panel.js —— 快捷播放面板（官方侧栏 tab 与低版本抽屉共用同一份内容）：当前壁纸 + 轮播 + 列表快切 + 声音 + 设置入口。列表虚拟滚动（spacer + 可视窗口）（构建期注入；勿手改本段）──
 				/**
 				 * quick-panel.js — 快捷播放面板（侧边栏的**唯一**内容）：当前壁纸 + 轮播 + 三档页签
@@ -17355,6 +17945,8 @@ window.__ModuleLoader__.load({
 				    { id: "wallpaper", get label() { return weT("壁纸"); } },
 				    { id: "appearance", get label() { return weT("外观"); } },
 				    { id: "playback", get label() { return weT("播放"); } },
+				    // 桌宠是"桌面上多出来的一只东西"，与壁纸/开机动画并列，不是它们的子功能。
+				    { id: "pets", get label() { return weT("桌宠"); } },
 				  ];
 				  // 页签记忆（同 picker-tab / qp-view 口径：仅 UI 状态，localStorage，不进 config.json）。
 				  const QP_TAB_KEY = "dsh-folia:qp-tab";
@@ -18069,6 +18661,7 @@ window.__ModuleLoader__.load({
 				          && React.createElement("div", { className: "we-qp__propsview we-qp__propsview--drill" }, renderUserPropsPanel()),
 				        // 开机动画档：整区就是那个面板（它自己管加载/下载/开关）。
 				        qpTab === "boot" && React.createElement(BootTabPanel, null),
+				        qpTab === "pets" && React.createElement(PetsTabPanel, null),
 				        !(qpTab === "wallpaper" && userPropsPanelOpen() && propsAvailable) && qpTab !== "boot" && (qpTab === "appearance"
 				          ? qpRenderAppearancePane(sel, {
 				            fontOpen, onToggleFontSection: toggleFontSection,
@@ -31401,6 +31994,10 @@ window.__ModuleLoader__.load({
 		  if (ctx.effect && typeof document !== "undefined") {
 		    ctx.effect(() => installSkinInterop() || undefined);
 		  }
+		  // 3c. 桌宠层：自己拉 /pets/list 决定是否出宠物，随 fiber 注销（不依赖面板打开过）。
+		  if (ctx.effect && typeof document !== "undefined") {
+		    ctx.effect(() => mountPetLayer() || undefined);
+		  }
 
 		  // 3. Chat-interface rope dock: the draggable pull-cord + glass repo side
 		  //    panel, portalled onto <body> under its own React root — independent of

package/lib/index.js

@@ -81,6 +81,7 @@ import { registerInventoryRoutes, warmInventorySiteCache } from './routes/invent
 import { registerModulesRoutes, warmModulesCache } from './routes/modules.js';
 import { registerBootRoutes } from './routes/boot.js';
 import { registerSiteThumbRoutes } from './routes/site-thumb.js';
+import { registerPetsRoutes } from './routes/pets.js';
 import { installBootInjection } from './boot/index.js';
 import { registerDiagRoutes } from './routes/diag.js';
 // 遮挡消息桥族（上游新增域模块）：hub 处理 x11 遮挡探针，路由对外暴露状态/控制面。
@@ -309,6 +310,9 @@ export function apply(ctx) {
   registerSiteThumbRoutes(webServer, { disposers, base: BASE, ensureImagePreview, log });
 
   // 启动预热（有意不阻塞）：站点清单与模块索引各拉一次，让第一次打开面板不冷。
+  // 桌宠：自渲染（不依赖第三方宠物插件）—— 站点当分发通道，我们负责安装与绘制。
+  registerPetsRoutes(webServer, { disposers, base: BASE, log });
+
   warmInventorySiteCache();
   warmModulesCache();
   installBootInjection(ctx, (m) => { try { log(m); } catch { /* ignore */ } });

package/lib/routes/pets.js

@@ -0,0 +1,459 @@
+/**
+ * routes/pets.js — **桌宠**（自渲染，不依赖第三方宠物插件）。
+ *
+ * 为什么自己渲染：桌宠的本质只是"一张雪碧图 + 每行的帧数/每帧时长 + 一个状态机"，
+ * 属于纯前端的绘帧问题，没有必须借助外部渲染器的理由。站点当分发通道，插件自己画。
+ *
+ * 数据契约（与 @linxin666/dsh-pet 的 manifest v2 兼容，方便复用现成宠物资产）：
+ *   <数据目录>/pets/<id>/pet.json          必填，见下
+ *   <数据目录>/pets/<id>/spritesheet.webp  必填
+ *
+ * 支持的最小形态（sprite2d）：
+ *   { petManifestVersion: 2, id, displayName, renderer: "sprite2d",
+ *     sprite2d: { spritesheetPath, cell: { width, height }, columns,
+ *                 frames?: number[], tracks?: { <状态>: { durations: number[] } } } }
+ * 几何缺省值按 dsh-pet 的 contract 走：8 列 × 9 行，每格 192×208。
+ *
+ * 纪律：
+ *   · **只读我们自己的目录**（`<数据目录>/pets`），不碰别的插件的资源目录；
+ *   · 安装只认带 `pet.json` 且 spritesheet 真实存在的目录，缺一不可；
+ *   · 任何异常都折成 4xx + 明确错误码，绝不把宿主打 500。
+ */
+import { createHash } from 'node:crypto';
+import { inflateRawSync } from 'node:zlib';
+import { createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, extname, join } from 'node:path';
+
+/** 注入契约（ADR-0013 D12）。 */
+export { unzip };
+export const DEPS = ['disposers', 'base', 'log'];
+
+const DEFAULT_COLUMNS = 8;
+const DEFAULT_ROWS = 9;
+const DEFAULT_CELL = { width: 192, height: 208 };
+const SHEET_MAX_BYTES = 24 * 1024 * 1024;
+const FETCH_TIMEOUT_MS = 30000;
+
+function dataRoot() {
+  const base = process.env.DSH_FOLIA_HOME || join(homedir(), '.dsh-folia');
+  return join(base, 'pets');
+}
+
+function siteBase() {
+  const raw = process.env.DSH_FOLIA_SITE;
+  if (typeof raw === 'string' && raw.trim().toLowerCase() === 'off') return null;
+  const base = (typeof raw === 'string' && raw.trim()) ? raw.trim() : 'https://folia-5ve.pages.dev';
+  return base.replace(/\/+$/, '');
+}
+
+/** 站点上的桌宠分类 slug（站点 `/api/public/categories` 里就有这一条）。 */
+const PET_CATEGORY = 'desktop-pet';
+
+function ensureDir(p) {
+  if (!existsSync(p)) mkdirSync(p, { recursive: true });
+  return p;
+}
+
+/**
+ * 一只已安装宠物的完整描述；`null` 表示这目录不是合法宠物（必须是**整份**：
+ * pet.json + 雪碧图都存在）。宁可少认一只，也不要在前端画出空白方块。
+ */
+function readPet(dir, id) {
+  const manifestPath = join(dir, 'pet.json');
+  let manifest;
+  try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')); } catch { return null; }
+  if (!manifest || typeof manifest !== 'object') return null;
+  const g = (manifest.sprite2d && typeof manifest.sprite2d === 'object') ? manifest.sprite2d : {};
+  const sheetName = typeof g.spritesheetPath === 'string' ? basename(g.spritesheetPath) : 'spritesheet.webp';
+  const sheetPath = join(dir, sheetName);
+  if (!existsSync(sheetPath)) return null;
+  const cell = (g.cell && Number(g.cell.width) > 0 && Number(g.cell.height) > 0)
+    ? { width: Number(g.cell.width), height: Number(g.cell.height) } : { ...DEFAULT_CELL };
+  const columns = Number(g.columns) > 0 ? Number(g.columns) : DEFAULT_COLUMNS;
+  const frames = Array.isArray(g.frames) && g.frames.length === DEFAULT_ROWS
+    ? g.frames.map((n) => Math.max(1, Math.min(columns, Number(n) || columns)))
+    : new Array(DEFAULT_ROWS).fill(columns);
+  // 轨道：只保留显式给出且长度合理的 durations；其余由前端用默认节奏。
+  const tracks = {};
+  if (g.tracks && typeof g.tracks === 'object') {
+    for (const [k, v] of Object.entries(g.tracks)) {
+      if (v && Array.isArray(v.durations) && v.durations.length) {
+        tracks[k] = { durations: v.durations.map((d) => Math.max(16, Number(d) || 120)) };
+      }
+    }
+  }
+  return {
+    id: String(manifest.id || id),
+    dirId: id,
+    name: String(manifest.displayName || manifest.id || id),
+    author: manifest.author ? String(manifest.author) : null,
+    license: manifest.license ? String(manifest.license) : null,
+    renderer: String(manifest.renderer || 'sprite2d'),
+    bytes: (() => { try { return statSync(sheetPath).size; } catch { return null; } })(),
+    cell, columns, frames, tracks,
+    sheet: '/folia/pets/sheet?v=' + encodeURIComponent(id),
+    // 音效：manifest 里显式给了 `sounds`（事件 → 包内文件）才生效；
+    // 没有就由前端用 Web Audio 合成，避免"没声音"变成默认行为。
+    sounds: (() => {
+      const src = (manifest.sounds && typeof manifest.sounds === 'object') ? manifest.sounds : null;
+      if (!src) return null;
+      const out = {};
+      for (const [ev, file] of Object.entries(src)) {
+        if (typeof file !== 'string') continue;
+        const rel = file.replace(/\\/g, '/');
+        if (!/^sounds\/[^/]+\.(ogg|mp3|wav|m4a|webm)$/i.test(rel)) continue;
+        const abs = join(dir, rel);
+        if (!existsSync(abs)) continue;
+        // 原样带 sounds/ 前缀：资源路由按 sounds/<文件> 白名单校验，剥掉前缀就对不上了。
+        out[ev] = '/folia/pets/asset?v=' + encodeURIComponent(id) + '&f=' + encodeURIComponent(rel);
+      }
+      return Object.keys(out).length ? out : null;
+    })(),
+  };
+}
+
+/** 列出本地已安装的宠物（目录扫描；坏目录静默跳过）。 */
+function listInstalled() {
+  const root = dataRoot();
+  const out = [];
+  let names = [];
+  try { names = readdirSync(root); } catch { return out; }
+  for (const name of names) {
+    const dir = join(root, name);
+    try { if (!statSync(dir).isDirectory()) continue; } catch { continue; }
+    const pet = readPet(dir, name);
+    if (pet) out.push(pet);
+  }
+  out.sort((a, b) => a.id.localeCompare(b.id));
+  return out;
+}
+
+/** 桌面宠物的配置（我们自己的文件，不写别人的配置）。 */
+function configPath() { return join(dirname(dataRoot()), 'pet-config.json'); }
+function readConfig() {
+  try {
+    const raw = JSON.parse(readFileSync(configPath(), 'utf8'));
+    return {
+      enabled: raw.enabled === true,
+      petId: typeof raw.petId === 'string' ? raw.petId : '',
+      scale: Number.isFinite(Number(raw.scale)) ? Math.min(3, Math.max(0.5, Number(raw.scale))) : 1,
+      sound: raw.sound === true,
+      volume: Number.isFinite(Number(raw.volume)) ? Math.min(1, Math.max(0, Number(raw.volume))) : 0.6,
+    };
+  } catch {
+    return { enabled: false, petId: '', scale: 1, sound: false, volume: 0.6 };
+  }
+}
+function writeConfig(next) {
+  const cur = readConfig();
+  const merged = {
+    enabled: next.enabled === undefined ? cur.enabled : Boolean(next.enabled),
+    petId: next.petId === undefined ? cur.petId : String(next.petId || ''),
+    scale: next.scale === undefined ? cur.scale : Math.min(3, Math.max(0.5, Number(next.scale) || 1)),
+    sound: next.sound === undefined ? cur.sound : Boolean(next.sound),
+    volume: next.volume === undefined ? cur.volume : Math.min(1, Math.max(0, Number(next.volume) || 0)),
+  };
+  try {
+    ensureDir(dirname(configPath()));
+    writeFileSync(configPath(), JSON.stringify(merged, null, 2) + '\n');
+  } catch { /* 只读盘：本次配置不落盘，但内存里仍按 merged 回给调用方 */ }
+  return merged;
+}
+
+function sendJson(res, status, body) {
+  const text = JSON.stringify(body);
+  res.statusCode = status;
+  if (typeof res.setHeader === 'function') {
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.setHeader('cache-control', 'no-store');
+  }
+  res.end(text);
+}
+
+/**
+ * 极简 zip 读取器：只做**取条目**这一件事（store / deflate 两种方法）。
+ *
+ * 为什么不引依赖：宠物包在我们自己手里生成（见 tools/upload-pets.mjs，store 模式），
+ * 而站点上别人上传的包也只有这两类方法。整个解析靠中央目录遍历，不猜、不流式、
+ * 且对每个条目做**大小与路径安全**检查 —— 一个 zip 解析器最该防的是路径穿越与 zip bomb。
+ *
+ * @returns {Map<string, Buffer>} 文件名 → 内容（只保留通过检查的条目）
+ */
+function unzip(buf, opts = {}) {
+  const maxEntry = Number(opts.maxEntry) || 24 * 1024 * 1024;
+  const maxTotal = Number(opts.maxTotal) || 64 * 1024 * 1024;
+  const out = new Map();
+  let total = 0;
+  // EOCD 在文件尾 22 字节起，最多带 64KB 注释
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65535); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new Error('not-a-zip');
+  const count = buf.readUInt16LE(eocd + 10);
+  let p = buf.readUInt32LE(eocd + 16);
+  for (let n = 0; n < count; n++) {
+    if (buf.readUInt32LE(p) !== 0x02014b50) throw new Error('bad-central');
+    const method = buf.readUInt16LE(p + 10);
+    const compSize = buf.readUInt32LE(p + 20);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const localOff = buf.readUInt32LE(p + 42);
+    const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+    p += 46 + nameLen + extraLen + commentLen;
+    // 路径安全：只收「根文件」与「sounds/<文件>」两种形态 —— 任何 `..`、绝对路径、
+    // 其它子目录一律丢弃。宠物包只需要雪碧图/清单/音效三类东西，收窄比放行安全。
+    const safeName = String(name).replace(/\\/g, '/');
+    const okShape = safeName.includes('..') || safeName.startsWith('/') ? false
+      : (safeName.indexOf('/') === -1 || /^sounds\/[^/]+$/.test(safeName));
+    if (!safeName || !okShape) continue;
+    if (compSize > maxEntry) continue;
+    const lNameLen = buf.readUInt16LE(localOff + 26);
+    const lExtraLen = buf.readUInt16LE(localOff + 28);
+    const dataAt = localOff + 30 + lNameLen + lExtraLen;
+    const comp = buf.subarray(dataAt, dataAt + compSize);
+    if (comp.length !== compSize) continue;
+    let data;
+    try {
+      data = method === 0 ? Buffer.from(comp) : method === 8 ? inflateRawSync(comp) : null;
+    } catch { data = null; }
+    if (!data) continue;
+    total += data.length;
+    if (total > maxTotal) throw new Error('too-large');
+    out.set(name, data);
+  }
+  return out;
+}
+
+function readBodyText(req, maxBytes = 64 * 1024) {
+  return new Promise((resolve) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (c) => {
+      size += c.length;
+      if (size > maxBytes) { resolve(''); req.destroy(); return; }
+      chunks.push(c);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', () => resolve(''));
+  });
+}
+
+export function registerPetsRoutes(webServer, c) {
+  const { disposers, base: BASE, log } = c;
+
+  // ── 站点桌宠清单（分类 desktop-pet） ──────────────────────────────────────
+  let siteCache = { at: 0, items: [], error: null };
+  async function fetchSitePets(force) {
+    if (!force && siteCache.items.length && Date.now() - siteCache.at < 60000) return siteCache;
+    const base = siteBase();
+    if (!base) { siteCache = { at: Date.now(), items: [], error: 'site-off' }; return siteCache; }
+    try {
+      const r = await fetch(base + '/api/public/wallpapers?category=' + PET_CATEGORY + '&limit=100', {
+        headers: { accept: 'application/json' }, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      });
+      if (!r.ok) throw new Error('http-' + r.status);
+      const doc = await r.json();
+      const list = (doc && doc.data && Array.isArray(doc.data.items)) ? doc.data.items : [];
+      const items = list.map((it) => {
+        const url = String((it && it.url) || '');
+        const abs = /^https?:/i.test(url) ? url : (url ? base + url : '');
+        const thumb = String((it && it.thumbUrl) || '');
+        return {
+          id: String((it && (it.slug || it.id)) || ''),
+          title: String((it && it.title) || ''),
+          bytes: Number(it && it.bytes) || null,
+          url: abs,
+          cover: thumb && /\.(jpg|jpeg|png|webp|gif|avif)(\?|#|$)/i.test(thumb)
+            ? (/^https?:/i.test(thumb) ? thumb : base + thumb) : null,
+        };
+      }).filter((x) => x.id && x.url);
+      siteCache = { at: Date.now(), items, error: null };
+      return siteCache;
+    } catch (e) {
+      siteCache = { at: Date.now(), items: siteCache.items, error: String((e && e.message) || e) };
+      return siteCache;
+    }
+  }
+
+  // ── GET /pets/list ────────────────────────────────────────────────────────
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/pets/list`,
+    handler: async (req, res) => {
+      const url = new URL(req.url || '/', 'http://x');
+      const force = url.searchParams.get('refresh') === '1';
+      const site = await fetchSitePets(force);
+      const installed = listInstalled();
+      const installedIds = new Set(installed.map((p) => p.dirId));
+      sendJson(res, 200, {
+        ok: true,
+        pets: installed,
+        site: site.items.map((it) => ({ ...it, installed: installedIds.has(it.id) })),
+        siteError: site.error,
+        config: readConfig(),
+      });
+    },
+  }));
+
+  // ── GET /pets/sheet?v=<dirId>（本地雪碧图） ───────────────────────────────
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/pets/sheet`,
+    handler: async (req, res) => {
+      let id = '';
+      try { id = new URL(req.url || '/', 'http://x').searchParams.get('v') || ''; } catch { id = ''; }
+      const dir = join(dataRoot(), String(id));
+      const pet = id && existsSync(dir) ? readPet(dir, id) : null;
+      if (!pet) { res.statusCode = 404; res.end(); return; }
+      const manifest = (() => { try { return JSON.parse(readFileSync(join(dir, 'pet.json'), 'utf8')); } catch { return {}; } })();
+      const sheetName = basename((manifest.sprite2d && manifest.sprite2d.spritesheetPath) || 'spritesheet.webp');
+      const file = join(dir, sheetName);
+      let size = 0;
+      try { size = statSync(file).size; } catch { /* 下面统一 404 */ }
+      if (!size || size > SHEET_MAX_BYTES) { res.statusCode = 404; res.end(); return; }
+      const type = extname(file).toLowerCase() === '.png' ? 'image/png'
+        : extname(file).toLowerCase() === '.gif' ? 'image/gif' : 'image/webp';
+      if (typeof res.setHeader === 'function') {
+        res.setHeader('content-type', type);
+        res.setHeader('content-length', String(size));
+        res.setHeader('cache-control', 'public, max-age=31536000, immutable');
+      }
+      res.statusCode = 200;
+      createReadStream(file).pipe(res);
+    },
+  }));
+
+  // ── GET /pets/asset?v=<dirId>&f=<相对路径>（包内音频等额外资源） ───────────
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/pets/asset`,
+    handler: async (req, res) => {
+      let q = null;
+      try { q = new URL(req.url || '/', 'http://x').searchParams; } catch { q = null; }
+      const id = q ? String(q.get('v') || '') : '';
+      const rel = q ? String(q.get('f') || '').replace(/\\/g, '/') : '';
+      if (!id || /[\\/]/.test(id) || id.includes('..') || !rel) { res.statusCode = 400; res.end(); return; }
+      // 只放行 sounds/ 下的已知音频扩展名：这条路由不充当通用文件读口。
+      if (!/^sounds\/[^/]+\.(ogg|mp3|wav|m4a|webm)$/i.test(rel)) { res.statusCode = 400; res.end(); return; }
+      const file = join(dataRoot(), id, rel);
+      let size = 0;
+      try { size = statSync(file).size; } catch { size = 0; }
+      if (!size || size > 16 * 1024 * 1024) { res.statusCode = 404; res.end(); return; }
+      const ext = extname(file).toLowerCase();
+      const type = ext === '.mp3' ? 'audio/mpeg' : ext === '.wav' ? 'audio/wav'
+        : ext === '.m4a' ? 'audio/mp4' : ext === '.webm' ? 'audio/webm' : 'audio/ogg';
+      if (typeof res.setHeader === 'function') {
+        res.setHeader('content-type', type);
+        res.setHeader('content-length', String(size));
+        res.setHeader('cache-control', 'public, max-age=31536000, immutable');
+      }
+      res.statusCode = 200;
+      createReadStream(file).pipe(res);
+    },
+  }));
+
+  // ── POST /pets/config（开关 / 选中 / 缩放） ───────────────────────────────
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/pets/config`,
+    handler: async (req, res) => {
+      if (req.method !== 'POST') { sendJson(res, 405, { ok: false, error: 'method' }); return; }
+      const text = await readBodyText(req);
+      let patch = {};
+      try { patch = JSON.parse(text || '{}'); } catch { sendJson(res, 400, { ok: false, error: 'bad-json' }); return; }
+      if (patch.petId && !existsSync(join(dataRoot(), String(patch.petId)))) {
+        sendJson(res, 404, { ok: false, error: 'not-installed' });
+        return;
+      }
+      const cfg = writeConfig(patch);
+      sendJson(res, 200, { ok: true, config: cfg });
+    },
+  }));
+
+  // ── POST /pets/install（从站点条目安装：下载 zip → 解开 → 校验） ─────────
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/pets/install`,
+    handler: async (req, res) => {
+      if (req.method !== 'POST') { sendJson(res, 405, { ok: false, error: 'method' }); return; }
+      const text = await readBodyText(req);
+      let id = '';
+      try { id = String((JSON.parse(text || '{}') || {}).id || '').trim(); } catch { id = ''; }
+      if (!id || /[\\/]/.test(id) || id.includes('..') || id.length > 120) { sendJson(res, 400, { ok: false, error: 'bad-id' }); return; }
+
+      const site = await fetchSitePets(false);
+      const item = site.items.find((x) => x.id === id);
+      if (!item) { sendJson(res, 404, { ok: false, error: 'not-on-site', detail: site.error || null }); return; }
+
+      let buf;
+      try {
+        const r = await fetch(item.url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (!r.ok) { sendJson(res, 502, { ok: false, error: 'http-' + r.status }); return; }
+        buf = Buffer.from(await r.arrayBuffer());
+      } catch (e) { sendJson(res, 502, { ok: false, error: 'fetch-failed', detail: String((e && e.message) || e) }); return; }
+
+      if (buf.length < 64 || buf[0] !== 0x50 || buf[1] !== 0x4b) {
+        sendJson(res, 422, { ok: false, error: 'not-a-zip' });
+        return;
+      }
+
+      let entries;
+      try { entries = unzip(buf); } catch (e) { sendJson(res, 422, { ok: false, error: 'bad-zip', detail: String((e && e.message) || e) }); return; }
+      const manifestRaw = entries.get('pet.json');
+      if (!manifestRaw) { sendJson(res, 422, { ok: false, error: 'no-manifest' }); return; }
+      let manifest;
+      try { manifest = JSON.parse(manifestRaw.toString('utf8')); } catch { sendJson(res, 422, { ok: false, error: 'bad-manifest' }); return; }
+      const sheetName = basename((manifest.sprite2d && manifest.sprite2d.spritesheetPath) || 'spritesheet.webp');
+      const sheet = entries.get(sheetName);
+      if (!sheet) { sendJson(res, 422, { ok: false, error: 'no-spritesheet', detail: sheetName }); return; }
+
+      const dir = join(dataRoot(), id);
+      try {
+        ensureDir(dir);
+        for (const [name, data] of entries) {
+          const rel = String(name).replace(/\\/g, '/');
+          const safe = rel.indexOf('/') === -1 ? basename(rel) : rel;   // sounds/x.ogg 保留一层
+          const target = join(dir, safe);
+          ensureDir(dirname(target));
+          writeFileSync(target, data);
+        }
+      } catch (e) {
+        try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+        sendJson(res, 500, { ok: false, error: 'write-failed', detail: String((e && e.message) || e) });
+        return;
+      }
+
+      const pet = readPet(dir, id);
+      if (!pet) { sendJson(res, 422, { ok: false, error: 'install-invalid' }); return; }
+      // 装完就选中它并开启 —— 用户点「安装」的意图就是「我要用它」。
+      const cfg = writeConfig({ enabled: true, petId: id });
+      if (typeof log === 'function') log('[pets] installed ' + id + ' (' + buf.length + ' bytes)');
+      sendJson(res, 200, { ok: true, id, pet, config: cfg });
+    },
+  }));
+
+  // ── POST /pets/remove（只删我们目录下的一只） ─────────────────────────────
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/pets/remove`,
+    handler: async (req, res) => {
+      if (req.method !== 'POST') { sendJson(res, 405, { ok: false, error: 'method' }); return; }
+      const text = await readBodyText(req);
+      let id = '';
+      try { id = String((JSON.parse(text || '{}') || {}).id || ''); } catch { id = ''; }
+      if (!id || /[\\/]/.test(id) || id.includes('..')) { sendJson(res, 400, { ok: false, error: 'bad-id' }); return; }
+      const dir = join(dataRoot(), id);
+      if (!existsSync(dir)) { sendJson(res, 404, { ok: false, error: 'not-installed' }); return; }
+      try { rmSync(dir, { recursive: true, force: true }); } catch { sendJson(res, 500, { ok: false, error: 'remove-failed' }); return; }
+      const cfg = readConfig();
+      if (cfg.petId === id) writeConfig({ petId: '' });
+      if (typeof log === 'function') log('[pets] removed ' + id);
+      sendJson(res, 200, { ok: true, id });
+    },
+  }));
+
+  return () => { /* 无长驻资源：路由随 disposers 归还 */ };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-folia",
-    "version":  "4.0.8",
+    "version":  "4.3.0",
     "description":  "Folia 壁纸引擎：把本机 Wallpaper Engine 壁纸搬进 DSH 界面（场景实时渲染 / 视频 / 网页），内置液态玻璃与 Folia 吉祥物，并可从自建站点拉取壁纸。单包形态（组件已合并）。",
     "type":  "module",
     "engines":  {
@@ -191,7 +191,8 @@
                     "verify:all":  "node test/run-guards.mjs all",
                     "prepack":  "node scripts/prepare.mjs",
                     "test:boot":  "node test/boot-http.mjs",
-                    "gate":  "node scripts/build-client.mjs \u0026\u0026 node test/run-guards.mjs smoke \u0026\u0026 node test/boot-http.mjs"
+                    "test:pets":  "node test/pets-http.mjs",
+                    "gate":  "node scripts/build-client.mjs \u0026\u0026 node test/run-guards.mjs smoke \u0026\u0026 node test/boot-http.mjs \u0026\u0026 node test/pets-http.mjs"
                 },
     "peerDependencies":  {
                              "@deepseek-ai/cordis":  "^4.0.4",