dsh-plugin-wallpaper-engine-pet-link 0.0.0-stage → 1.4.0

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# 桌宠联动子包
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+本包只包含官方 pet 桥接、四条演出排播、调参面板、九段定制动画及五张配图。不包含 pet 渲染器、Electron、完整基础素材或第三方补丁安装器。
+
+## 使用
+
+1. 按仓库的完整源码部署步骤安装 Wallpaper 的主包和七个子包。
+2. 自行安装并启用官方 [dsh-pet](https://github.com/PC2005-cloud/dsh-pet)，将目标设为网页显示。官方需提供同页 `petApi7340.pose/progress` 和 `/dsh-pet-7340/` 下的 config、lock、anim、position、throw 接口。审计基线为官方提交 `7440b963ab7fb962cb7694e094aa0c9c7a438a7b`；同为 `0.3.7` 的旧构建不一定有这些接口。
+3. 将 Wallpaper 吉祥物设为官方侧栏模式，按 `Ctrl+Shift+D` 打开面板，刷新并选择目标 petId，再分别试跑四条逻辑。
+
+没有官方 pet、服务缺失、目标隐藏或联动关闭时，只停用联动，吉祥物原生侧栏操作继续可用。不会自动安装、启用或修改官方 pet。目标缺失不会自动改控另一只宠物。
+
+## 控制边界
+
+- 宿主按 petId 协调页面，保管官方锁凭证并顺序下发白名单指令；短租约、失锁和旧响应清理不会强占新运行。
+- 官方同一 pet 的动作会同步到其他显示端。`surface` 不是单页定向，本包不承诺跨端隔离。
+- 发起页面自绘气泡并读取官方 pose 跟随。动作结束释放官方唯一锁后，气泡可以继续存在；不调用官方 broadcast 或 bubble/clear，也不注入桌面透明窗。
+- 侧栏、抓绳、踢腿弹飞、哈气四条排播使用同页 playbackId 与实际视频进度触发节点。位置和抛掷交给官方 `position/throw`；不查询宠物 DOM、不改 React 私有字段、不逐帧发 HTTP。
+- 官方直线位移按墙钟推进，不能保证视频缓冲时的逐帧贴边同步。旧私有运动面的精度不作为当前接口已实现的能力。
+
+## 参数与验证
+
+面板提供目标选择、四逻辑参数、运行、停止、重置和 JSON 导出。五张气泡各有出现与隐藏的动作、开始/结束锚点及毫秒偏移；重置当前逻辑同时清除该逻辑的气泡节点。参数是当前页运行时覆盖，刷新前请导出。
+
+```sh
+npm run build
+npm run verify:pet-link
+```
+
+回归覆盖协议协调、真实本地 HTTP、素材 Range、独立气泡生命周期、四条排播、缺席回退和卸载竞态。`npm run verify:pet-link:integration` 检查真实 Cordis 配置更新与启停；`npm run verify:pet-link:browser` 检查独立浏览器中的自有气泡、配图加载及调参面板。浏览器夹具不等于官方完整 React 宠物或桌面窗口的视觉验收；不能把接口单测当成所有动画均已真机验收。
+
+## 从旧版本迁移
+
+内置 pet 和修改第三方文件的安装器已退役。旧 profile 里的派生依赖、bundle 选择、数据及曾经安装的外部补丁不会自动清除。关闭宿主后先停用旧内置 bundle，再更新 Wallpaper；外部补丁应通过其原备份恢复或重装官方包，不对活动安装做故障注入。
+
+本包保留联动定制素材，不包含官方完整资源、字体及个人数据。代码许可证不替代素材授权；素材分发与商用范围须分别确认。本轮不发布 npm。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: wallpaper-engine-pet-link
+      name: dsh-plugin-wallpaper-engine-pet-link

package/lib/client.pet-link.js

@@ -0,0 +1,641 @@
+window.__ModuleLoader__.load({
+	id: "dsh-plugin-wallpaper-engine-pet-link",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		const host = require("dsh-plugin-wallpaper-engine");
+				// ── 内联模块：packages/pet-link/src/official-pet.js —— 官方 pet 同页只读实况与独立气泡客户端（构建期注入；勿手改本段）──
+				/** 官方桥接客户端；独立气泡不占用、不清理官方原生气泡。 */
+				function createOfficialPetClient(ctx, options) {
+				  const doc = options.document || document;
+				  const raf = options.requestAnimationFrame || requestAnimationFrame;
+				  const caf = options.cancelAnimationFrame || cancelAnimationFrame;
+				  const later = options.setTimeout || setTimeout;
+				  const clear = options.clearTimeout || clearTimeout;
+				  const viewport = options.viewport || (() => ({ width: window.innerWidth, height: window.innerHeight }));
+				  const pageId = options.pageId || crypto.randomUUID();
+				  let disposed = false;
+				  let generation = 0;
+				  let run = null;
+				  let bubble = null;
+				  let heartbeat = null;
+				  let playbackId = null;
+				  const service = () => {
+				    try { return ctx.get('petApi7340') || null; } catch { return null; }
+				  };
+				  const rpc = async input => {
+				    try { return await options.request(input); } catch { return { ok: false, reason: 'transport-error' }; }
+				  };
+				  const hideBubble = () => {
+				    if (!bubble) return;
+				    const own = bubble; bubble = null;
+				    clear(own.timer); caf(own.frame); own.node.remove();
+				  };
+				  const finish = async () => {
+				    generation++;
+				    const own = run; run = null; playbackId = null;
+				    clear(heartbeat); heartbeat = null;
+				    return own ? rpc({ ...own.ticket, op: 'finish' }) : { ok: true };
+				  };
+				  const stop = () => { hideBubble(); return finish(); };
+				  const armHeartbeat = own => {
+				    heartbeat = later(async () => {
+				      if (disposed || run !== own) return;
+				      const result = await rpc({ ...own.ticket, op: 'heartbeat' });
+				      if (run !== own) return;
+				      if (!result?.ok || service() !== own.service) { await stop(); return; }
+				      armHeartbeat(own);
+				    }, 1000);
+				  };
+				  const command = async action => {
+				    const own = run;
+				    if (!own || disposed) return { ok: false, reason: 'run-lost' };
+				    if (service() !== own.service) { await stop(); return { ok: false, reason: 'service-lost' }; }
+				    const result = await rpc({ ...own.ticket, op: 'command', action });
+				    if (run !== own) return { ok: false, reason: 'run-lost' };
+				    if (!result?.ok) await stop();
+				    return result;
+				  };
+				  const client = {
+				    async begin(petId) {
+				      hideBubble();
+				      const finishing = finish();
+				      const epoch = generation;
+				      await finishing;
+				      if (disposed) return { ok: false, reason: 'client-disposed' };
+				      if (epoch !== generation) return { ok: false, reason: 'run-lost' };
+				      const api = service();
+				      if (!api || typeof api.pose !== 'function' || typeof api.progress !== 'function' || !api.pose(petId)) {
+				        return { ok: false, reason: 'client-service-unavailable' };
+				      }
+				      const ticket = await rpc({ op: 'start', petId, pageId });
+				      if (!ticket?.ok) return ticket;
+				      if (disposed || epoch !== generation || api !== service()) {
+				        await rpc({ ...ticket, op: 'finish' });
+				        return { ok: false, reason: 'client-disposed' };
+				      }
+				      run = { ticket, service: api }; armHeartbeat(run);
+				      return ticket;
+				    },
+				    async play(name, facing) {
+				      const own = run;
+				      const result = await command({ kind: 'anim', name, facing });
+				      if (result?.ok && run === own) playbackId = result.playbackId;
+				      return result;
+				    },
+				    position(x, y, mode, duration) { return command({ kind: 'position', x, y, mode, duration }); },
+				    throwPet(angle, power) { return command({ kind: 'throw', angle, power }); },
+				    progress() {
+				      if (!run || service() !== run.service || !playbackId) return null;
+				      const value = run.service.progress(run.ticket.petId);
+				      return value?.playbackId === playbackId ? value : null;
+				    },
+				    showBubble({ text = '', image = null, duration = 5000 }) {
+				      if (!run || disposed || !Number.isFinite(duration) || duration <= 0 || duration > 180000) return false;
+				      if (image !== null && (!Number.isInteger(image) || image < 0 || image > 4 || !options.bubbleUrl)) return false;
+				      if (typeof text !== 'string' || text.length > 2000) return false;
+				      const ownRun = run;
+				      const size = Number(options.sizeOf(ownRun.ticket.petId));
+				      if (!Number.isFinite(size) || size <= 0 || size > 1000) return false;
+				      hideBubble();
+				      const node = doc.createElement('div');
+				      node.setAttribute('data-we-official-pet-bubble', ownRun.ticket.runId);
+				      Object.assign(node.style, { position: 'fixed', pointerEvents: 'none', zIndex: '50',
+				        width: 'min(240px, calc(100vw - 16px))', boxSizing: 'border-box', overflowWrap: 'anywhere',
+				        padding: '8px', borderRadius: '8px', background: 'Canvas', color: 'CanvasText',
+				        border: '1px solid GrayText', transform: 'translate(-50%, -100%)' });
+				      node.textContent = text;
+				      if (image !== null) {
+				        const picture = doc.createElement('img');
+				        picture.src = options.bubbleUrl(image); picture.alt = '';
+				        Object.assign(picture.style, { display: 'block', width: '180px', maxWidth: '100%', height: '180px', objectFit: 'contain' });
+				        node.appendChild(picture);
+				      }
+				      const own = { node, timer: null, frame: null };
+				      const render = () => {
+				        if (bubble !== own) return;
+				        const pose = service() === ownRun.service ? ownRun.service.pose(ownRun.ticket.petId) : null;
+				        if (!pose || !Number.isFinite(pose.x) || !Number.isFinite(pose.y)) { stop(); return; }
+				        const view = viewport();
+				        const box = node.getBoundingClientRect?.() || { width: Math.min(240, view.width - 16), height: 80 };
+				        if (box.height > view.height - 16) { hideBubble(); return; }
+				        node.style.left = `${Math.max(box.width / 2 + 8, Math.min(view.width - box.width / 2 - 8, pose.x * view.width))}px`;
+				        node.style.top = `${Math.max(box.height + 8, Math.min(view.height - 8, pose.y * view.height - size / 2 - 8))}px`;
+				        own.frame = raf(render);
+				      };
+				      bubble = own; doc.body.appendChild(node); render();
+				      if (bubble !== own) return false;
+				      own.timer = later(() => { if (bubble === own) hideBubble(); }, duration);
+				      return bubble === own;
+				    },
+				    hideBubble,
+				    finish,
+				    dispose() { if (!disposed) { disposed = true; stop(); } },
+				  };
+				  if (typeof ctx.effect === 'function') ctx.effect(() => () => client.dispose());
+				  return client;
+				}
+
+				// ── 内联模块：packages/pet-link/src/pet-link-tuner.js —— 页内调参面板（Ctrl+Shift+D；调试工具，非产品功能；自 packages/pet-link/src/pet-link-tuner.js 原样迁出内联通路）（构建期注入；勿手改本段）──
+				/** 官方联动调参面板；仅暴露原生接口实际支持的参数，不保留无效的逐帧宠物 DOM 旋钮。 */
+				function createOfficialPetTuner(link, options = {}) {
+				  const doc = options.document || document;
+				  let root = null, logic = 'sidebar', installed = false;
+				  const weT = options.translate || (value => value);
+				  const fields = [
+				    ['sidebarWalkMs', weT('走位时长（毫秒）')], ['braceMs', weT('准备时长（毫秒）')],
+				    ['slowOpenMs', weT('侧栏展开（毫秒）')], ['openDelayMs', weT('展开延迟（毫秒）')],
+				    ['bubbleMs', weT('气泡时长（毫秒）')], ['holdMaxMs', weT('等待关闭（毫秒）')], ['eggAt', weT('彩蛋触发次数')],
+				    ['mascotOpenAtMs', weT('抓绳触发（毫秒）')], ['mascotRopeDownPx', weT('绳子下拉（像素）')],
+				    ['mascotReleaseAtMs', weT('绳子释放（毫秒）')], ['egg1FlingPower', weT('原生抛掷力度')],
+				    ['egg1LeadMs', weT('踢腿提前量（毫秒）')], ['egg1PostLandMs', weT('落地停留（毫秒）')],
+				    ['egg2LeadMs', weT('哈气提前量（毫秒）')], ['egg2OpenAtPct', weT('哈气展开进度（%）')],
+				  ];
+				  const labels = { sidebar: weT('拉动侧边栏'), mascot: weT('抓绳互动'), egg1: weT('踢开并弹飞'), egg2: weT('站立哈气') };
+				  const text = value => options.translate ? options.translate(value) : value;
+				  function element(tag, label) {
+				    const node = doc.createElement(tag);
+				    if (label) node.textContent = text(label);
+				    return node;
+				  }
+				  function button(label, title, action) {
+				    const node = element('button', label);
+				    node.type = 'button'; node.title = text(title); node.setAttribute('aria-label', text(title));
+				    node.style.cssText = 'min-width:32px;min-height:32px;border:1px solid GrayText;background:ButtonFace;color:ButtonText;border-radius:4px;cursor:pointer';
+				    node.addEventListener('click', action);
+				    return node;
+				  }
+				  function sync() {
+				    if (!root) return;
+				    const value = link.tuner.snapshot();
+				    root.querySelector('[data-status]').textContent = value.busy ? value.phase : value.reason || text(weT('联动可用'));
+				    const target = root.querySelector('[data-target]');
+				    target.replaceChildren();
+				    const pets = value.pets.filter(item => ['web', 'both'].includes(item.display));
+				    if (!pets.some(item => item.id === value.target)) pets.unshift({ id: value.target, name: value.target });
+				    for (const pet of pets) {
+				      const option = element('option'); option.value = pet.id; option.textContent = pet.name || pet.id;
+				      option.selected = pet.id === value.target; target.appendChild(option);
+				    }
+				    for (const input of root.querySelectorAll('[data-param]')) {
+				      const key = input.getAttribute('data-param');
+				      input.value = String(value.logicTuning[logic]?.[key] ?? value.defaults[key]);
+				    }
+				    for (const group of root.querySelectorAll('[data-bubble-group]')) {
+				      const id = group.getAttribute('data-bubble-group');
+				      const spec = PET_BUBBLE_SPECS.find(item => item.id === id);
+				      group.hidden = spec.logic !== logic;
+				      for (const row of group.querySelectorAll('[data-bubble-rule]')) {
+				        const rule = value.bubbleTiming[id]?.[row.getAttribute('data-bubble-rule')];
+				        row.querySelector('[data-bubble-action]').value = rule?.action || '';
+				        row.querySelector('[data-bubble-edge]').value = rule?.edge || 'start';
+				        row.querySelector('[data-bubble-offset]').value = String(rule?.offsetMs || 0);
+				      }
+				    }
+				    for (const tab of root.querySelectorAll('[data-logic]')) tab.setAttribute('aria-selected', String(tab.getAttribute('data-logic') === logic));
+				  }
+				  function open() {
+				    if (!root) {
+				      root = element('section'); root.setAttribute('data-pet-tuner', 'official');
+				      root.setAttribute('aria-label', text(weT('桌宠联动调参'))); root.setAttribute('role', 'dialog');
+				      root.style.cssText = 'position:fixed;inset:8px 8px auto auto;width:min(460px,calc(100vw - 16px));max-height:calc(100vh - 16px);overflow:auto;box-sizing:border-box;padding:12px;border:1px solid GrayText;border-radius:8px;background:Canvas;color:CanvasText;z-index:1000;font:13px/1.5 system-ui;letter-spacing:0';
+				      const header = element('header'); header.style.cssText = 'display:flex;align-items:center;gap:8px;margin-bottom:8px';
+				      const heading = element('strong', weT('桌宠联动调参')); heading.style.flex = '1'; header.appendChild(heading);
+				      header.appendChild(button('↻', weT('刷新桌宠'), () => { link.warmup().then(sync); }));
+				      header.appendChild(button('■', weT('停止联动'), () => { link.tuner.cancel(); sync(); }));
+				      header.appendChild(button('×', weT('关闭'), close)); root.appendChild(header);
+				      const targetLabel = element('label', weT('目标桌宠')); targetLabel.style.cssText = 'display:grid;grid-template-columns:100px minmax(0,1fr);gap:8px';
+				      const target = element('select'); target.setAttribute('data-target', ''); target.style.minWidth = '0';
+				      target.addEventListener('change', () => { link.tuner.setTarget(target.value); link.warmup().then(sync); });
+				      targetLabel.appendChild(target); root.appendChild(targetLabel);
+				      const tabs = element('div'); tabs.setAttribute('role', 'tablist'); tabs.style.cssText = 'display:flex;flex-wrap:wrap;gap:4px;margin:8px 0';
+				      for (const key of PET_TUNER_LOGICS) {
+				        const tab = button(labels[key], labels[key], () => { logic = key; sync(); });
+				        tab.setAttribute('role', 'tab'); tab.setAttribute('data-logic', key); tabs.appendChild(tab);
+				      }
+				      root.appendChild(tabs);
+				      for (const [key, label] of fields) {
+				        const row = element('label', label); row.style.cssText = 'display:grid;grid-template-columns:minmax(0,1fr) 100px;gap:8px;align-items:center;margin:5px 0;overflow-wrap:anywhere';
+				        const input = element('input'); input.type = 'number'; input.min = '0'; input.step = key === 'egg1FlingPower' ? '0.1' : '1';
+				        input.style.cssText = 'min-width:0;width:100%;box-sizing:border-box'; input.setAttribute('data-param', key);
+				        input.addEventListener('change', () => {
+				          if (!link.tuner.setForLogic(logic, key, Number(input.value))) sync();
+				        }); row.appendChild(input); root.appendChild(row);
+				      }
+				      for (const spec of PET_BUBBLE_SPECS) {
+				        const group = element('fieldset'); group.setAttribute('data-bubble-group', spec.id);
+				        group.style.cssText = 'margin:10px 0 0;padding:8px;min-width:0;border:1px solid GrayText';
+				        group.appendChild(element('legend', spec.text(weT)));
+				        for (const [edge, label] of [['show', weT('出现')], ['hide', weT('隐藏')]]) {
+				          const row = element('div'); row.setAttribute('data-bubble-rule', edge);
+				          row.style.cssText = 'display:grid;grid-template-columns:32px minmax(0,1fr) 60px 72px;gap:4px;margin:4px 0;align-items:center';
+				          row.appendChild(element('span', label));
+				          const action = element('select'); action.setAttribute('data-bubble-action', '');
+				          action.setAttribute('aria-label', edge === 'show' ? weT('出现动作') : weT('隐藏动作')); action.style.minWidth = '0';
+				          for (const [key, name] of [['', weT('默认')], ...Object.keys(PET_ANIM).map(key => [key, key])]) {
+				            const option = element('option', name); option.value = key; action.appendChild(option);
+				          }
+				          const anchor = element('select'); anchor.setAttribute('data-bubble-edge', '');
+				          anchor.setAttribute('aria-label', edge === 'show' ? weT('出现时间锚点') : weT('隐藏时间锚点'));
+				          for (const [key, name] of [['start', weT('开始')], ['end', weT('结束')]]) {
+				            const option = element('option', name); option.value = key; anchor.appendChild(option);
+				          }
+				          const offset = element('input'); offset.type = 'number'; offset.min = '-180000'; offset.max = '180000'; offset.step = '1';
+				          offset.style.cssText = 'width:100%;min-width:0;box-sizing:border-box';
+				          offset.setAttribute('data-bubble-offset', ''); offset.setAttribute('aria-label', edge === 'show' ? weT('出现偏移（毫秒）') : weT('隐藏偏移（毫秒）'));
+				          const change = () => {
+				            const config = { ...link.tuner.snapshot().bubbleTiming[spec.id] };
+				            if (action.value) config[edge] = { action: action.value, edge: anchor.value, offsetMs: Number(offset.value) };
+				            else delete config[edge];
+				            if (!link.tuner.setBubbleTiming(spec.id, config)) sync();
+				          };
+				          for (const input of [action, anchor, offset]) { input.addEventListener('change', change); row.appendChild(input); }
+				          group.appendChild(row);
+				        }
+				        root.appendChild(group);
+				      }
+				      const actions = element('div'); actions.style.cssText = 'display:flex;flex-wrap:wrap;gap:8px;margin-top:10px';
+				      actions.appendChild(button('▶', weT('运行当前逻辑'), () => { link.tuner.run(logic).then(sync); sync(); }));
+				      actions.appendChild(button('↶', weT('重置当前逻辑'), () => { link.tuner.reset(logic); sync(); }));
+				      actions.appendChild(button('↓', weT('导出 JSON'), () => {
+				        const out = root.querySelector('textarea'); out.value = JSON.stringify(link.tuner.snapshot(), null, 2); out.hidden = false; out.focus(); out.select();
+				      })); root.appendChild(actions);
+				      const status = element('output'); status.setAttribute('data-status', ''); status.setAttribute('aria-live', 'polite'); root.appendChild(status);
+				      const out = element('textarea'); out.hidden = true; out.readOnly = true; out.rows = 6;
+				      out.setAttribute('aria-label', text(weT('当前调参 JSON'))); out.style.cssText = 'width:100%;box-sizing:border-box;margin-top:8px'; root.appendChild(out);
+				      doc.body.appendChild(root);
+				    }
+				    root.hidden = false; sync(); link.warmup().then(sync); return true;
+				  }
+				  function close() { if (root) root.hidden = true; return false; }
+				  const keydown = event => {
+				    if (!event.ctrlKey || !event.shiftKey || String(event.key).toLowerCase() !== 'd') return;
+				    event.preventDefault(); event.stopImmediatePropagation();
+				    if (root && !root.hidden) close(); else open();
+				  };
+				  return {
+				    open, close, toggle() { return root && !root.hidden ? close() : open(); }, isOpen() { return Boolean(root && !root.hidden); },
+				    install() { if (!installed) { doc.addEventListener('keydown', keydown, true); installed = true; } },
+				    dispose() { doc.removeEventListener('keydown', keydown, true); installed = false; root?.remove(); root = null; },
+				  };
+				}
+
+				// ── 内联模块：packages/pet-link/src/pet-link.js —— 桌宠联动的排播 / 吉祥物触摸面 / 能力探测（自 packages/pet-link/src/pet-link.js 原样迁出内联通路）（构建期注入；勿手改本段）──
+				/** 官方原生联动。只读同页服务，所有宠物写操作经宿主协调器，不查询或改写宠物 DOM。 */
+				const PET_BASE = '/dsh-pet-7340';
+				const PET_ANIM = {
+				  walkRight: '通用-右侧螃蟹步-dshwe', walkLeft: '通用-左侧螃蟹步-dshwe',
+				  brace: '侧边栏-蓄力准备往后拉-dshwe', pull: '侧边栏-后拉接疲态结束-dshwe',
+				  mascotTumble: '吉祥物-跳抓眩晕落地起身-dshwe', eggKick: '彩蛋-侧边栏-半身转向踢腿-dshwe',
+				  eggFlung: '彩蛋-侧边栏-被弹飞-dshwe', eggLand: '彩蛋-侧边栏-落地-dshwe', eggHiss: '彩蛋-吉祥物-哈气-dshwe',
+				};
+				const PET_HOLD = { walkRight: 5167, walkLeft: 5167, brace: 5167, pull: 10125,
+				  mascotTumble: 8000, eggKick: 5167, eggFlung: 10125, eggLand: 5167, eggHiss: 5167 };
+				const PET_TUNE_DEFAULTS = {
+				  sidebarWalkMs: 5167, braceMs: 1000, slowOpenMs: 8125, openDelayMs: 500,
+				  bubbleMs: 3000, holdMaxMs: 180000, eggAt: 3, mascotOpenAtMs: 2500,
+				  mascotRopeDownPx: 40, mascotReleaseAtMs: 2920, egg1FlingPower: 1,
+				  egg1LeadMs: 600, egg1PostLandMs: 600, egg2LeadMs: 600, egg2OpenAtPct: 35,
+				};
+				const PET_TUNER_LOGICS = ['sidebar', 'mascot', 'egg1', 'egg2'];
+				const PET_BUBBLE_SPECS = [
+				  { id: 'sidebar', logic: 'sidebar', image: 0, text(weT = value => value) { return weT('累死本鲸了，给我添两碗饭'); } },
+				  { id: 'mascot', logic: 'mascot', image: 1, text(weT = value => value) { return weT('可以换壁纸了，不要用××√哦'); } },
+				  { id: 'egg1Angry', logic: 'egg1', image: 2, text(weT = value => value) { return weT('偶鲸鲸！！！'); } },
+				  { id: 'egg1Land', logic: 'egg1', image: 3, text(weT = value => value) { return weT('哇啊啊啊啊啊！！！'); } },
+				  { id: 'egg2', logic: 'egg2', image: 4, text(weT = value => value) { return weT('？！欺负一只肥鱼！？'); } },
+				];
+
+				function createOfficialPetPerformer(options) {
+				  const now = options.now || Date.now;
+				  const later = options.setTimeout || setTimeout;
+				  const clear = options.clearTimeout || clearTimeout;
+				  const wait = options.wait || (ms => new Promise(resolve => later(resolve, ms)));
+				  const view = options.viewport || (() => ({ width: window.innerWidth, height: window.innerHeight }));
+				  const doc = options.document || (typeof document === 'undefined' ? null : document);
+				  const storage = options.storage === undefined ? (typeof localStorage === 'undefined' ? null : localStorage) : options.storage;
+				  const storageKey = 'dsh-we-official-pet-target';
+				  let target = 'main';
+				  try { target = storage?.getItem(storageKey) || target; } catch { /* 私密模式仍可用。 */ }
+				  const state = { available: false, reason: 'official-unavailable', pets: [], epoch: 0, busy: false,
+				    phase: 'idle', logic: '', farCount: 0, nearCount: 0, tuning: {}, bubbleTiming: {}, timer: null,
+				    client: null, sidebar: null, disposed: false, home: null, activeLogic: 'sidebar' };
+				  const tune = (key, logic = state.activeLogic) => state.tuning[logic]?.[key] ?? PET_TUNE_DEFAULTS[key];
+				  const service = () => { try { return options.getContext()?.get('petApi7340') || null; } catch { return null; } };
+				  const pet = () => state.pets.find(item => item.id === target);
+				  const pose = () => { try { return service()?.pose(target) || null; } catch { return null; } };
+				  function ensureClient() {
+				    if (!state.client) state.client = createOfficialPetClient({ get: () => service() }, {
+				      ...options, document: doc, viewport: view, sizeOf: () => pet()?.size,
+				    });
+				    return state.client;
+				  }
+				  async function probe() {
+				    const epoch = state.epoch;
+				    try {
+				      const result = await options.fetchTargets();
+				      if (epoch !== state.epoch || state.disposed) return false;
+				      state.pets = result?.ok && Array.isArray(result.pets) ? result.pets : [];
+				      const api = service(), chosen = pet();
+				      state.reason = !result?.ok ? result?.reason || 'official-unavailable'
+				        : !chosen ? 'unknown-pet'
+				          : !['web', 'both'].includes(chosen.display) ? 'pet-not-displayed'
+				            : !api || typeof api.pose !== 'function' || typeof api.progress !== 'function' || !pose()
+				              ? 'client-service-unavailable' : '';
+				      state.available = !state.reason;
+				    } catch { state.available = false; state.reason = 'official-unavailable'; }
+				    return state.available;
+				  }
+				  const clamp = value => Math.max(0, Math.min(1, value));
+				  function point() {
+				    const value = pose();
+				    if (!value || ![value.x, value.y].every(Number.isFinite)) throw new Error('pose-unavailable');
+				    return value;
+				  }
+				  function sidebarCall(method, ...args) {
+				    const fn = state.sidebar?.[method];
+				    return typeof fn === 'function' ? fn(...args) : undefined;
+				  }
+				  function cancel() {
+				    state.epoch++; state.busy = false;
+				    const oldClient = state.client;
+				    state.client = null;
+				    oldClient?.dispose();
+				    sidebarCall('commit');
+				    options.restoreRope?.();
+				  }
+				  function fallback() {
+				    let handled = false;
+				    try { handled = options.fallback() === true; } catch { /* 不影响壁纸主界面。 */ }
+				    return { logic: 'disabled', phase: 'done', busy: false, fallback: handled, reason: state.reason };
+				  }
+				  async function run(logic, gesture = false) {
+				    if (state.busy) return { logic: 'busy', busy: true };
+				    if (!PET_TUNER_LOGICS.includes(logic) && !gesture) return { logic: 'invalid', busy: false };
+				    state.busy = true;
+				    const epoch = state.epoch;
+				    const alive = () => epoch === state.epoch && !state.disposed && Boolean(pose());
+				    const check = () => { if (!alive()) throw new Error('run-lost'); };
+				    const assertResult = result => { if (!result?.ok) throw new Error(result?.reason || 'official-unavailable'); };
+				    let client, released = false, openedSidebar = false;
+				    const openSidebar = () => { openedSidebar = true; sidebarCall('open'); };
+				    try {
+				      if (!await probe() || !alive()) return gesture ? { logic: 'disabled', busy: false } : fallback();
+				      client = ensureClient();
+				      assertResult(await client.begin(target)); check();
+				      state.home = point(); state.logic = logic; state.activeLogic = logic;
+				      const hooks = new Set();
+				      const shown = new Map();
+				      const hide = id => { if (shown.has(id)) { client.hideBubble(); shown.clear(); } };
+				      const show = id => {
+				        const spec = PET_BUBBLE_SPECS.find(item => item.id === id);
+				        if (!spec) return;
+				        shown.clear(); shown.set(id, now());
+				        client.showBubble({ text: spec.text(options.translate), image: spec.image, duration: Math.max(1, tune('bubbleMs')) });
+				      };
+				      const node = (action, seconds, duration) => {
+				        for (const spec of PET_BUBBLE_SPECS.filter(item => item.logic === logic)) {
+				          const config = state.bubbleTiming[spec.id];
+				          for (const edge of ['show', 'hide']) {
+				            const rule = config?.[edge];
+				            if (!rule || rule.action !== action || hooks.has(spec.id + edge)) continue;
+				            const at = (rule.edge === 'end' ? duration * 1000 : 0) + rule.offsetMs;
+				            if (seconds * 1000 < at) continue;
+				            hooks.add(spec.id + edge);
+				            if (edge === 'show') show(spec.id); else hide(spec.id);
+				          }
+				        }
+				      };
+				      const defaultShow = id => { if (!state.bubbleTiming[id]?.show) show(id); };
+				      const defaultHide = id => { if (!state.bubbleTiming[id]?.hide) hide(id); };
+				      const clip = async (key, tick, limitMs = null) => {
+				        check(); state.phase = key;
+				        const current = point();
+				        assertResult(await client.play(PET_ANIM[key], current.facing === 'right' ? 'right' : 'left')); check();
+				        const deadline = now() + Math.max(30000, PET_HOLD[key] + 20000);
+				        let started = false;
+				        while (alive() && now() < deadline) {
+				          const p = client.progress();
+				          if (p && Number.isFinite(p.currentTime) && Number.isFinite(p.duration) && p.duration > 0) {
+				            started = true;
+				            node(key, p.currentTime, p.duration);
+				            if (tick) await tick(p.currentTime * 1000, p.duration * 1000);
+				            if (p.currentTime >= p.duration - 0.045 || (limitMs !== null && p.currentTime * 1000 >= limitMs)) return;
+				          } else if (started) throw new Error('playback-replaced');
+				          await wait(32);
+				        }
+				        throw new Error('playback-timeout');
+				      };
+				      const move = async (destination, duration = 600) => {
+				        check();
+				        assertResult(await client.position(clamp(destination.x), clamp(destination.y), 'line', duration));
+				        check();
+				      };
+				      const walk = async destination => {
+				        const current = point();
+				        const key = destination.x < current.x ? 'walkLeft' : 'walkRight';
+				        let moving = false;
+				        await clip(key, async () => { if (!moving) { moving = true; await move(destination, tune('sidebarWalkMs')); } });
+				      };
+				      const edgePoint = () => {
+				        const width = view().width;
+				        const edge = sidebarCall('edgeX');
+				        return { x: clamp(((Number.isFinite(edge) ? edge : width) - Number(pet()?.size || 180) * 0.15) / width), y: point().y };
+				      };
+				      if (gesture) {
+				        await clip(logic === 'grab' ? 'brace' : 'pull', null, logic === 'grab' ? tune('braceMs') : null);
+				      } else if (logic === 'sidebar') {
+				        await walk(edgePoint());
+				        await clip('brace', null, tune('braceMs'));
+				        let opened = false;
+				        await clip('pull', async ms => {
+				          if (!opened && ms >= tune('openDelayMs')) {
+				            opened = true; sidebarCall('beginPull', tune('slowOpenMs')); openSidebar();
+				            await move(edgePoint(), tune('slowOpenMs'));
+				          }
+				        });
+				        if (!opened) openSidebar();
+				        sidebarCall('commit'); defaultShow('sidebar');
+				      } else if (logic === 'mascot') {
+				        const rope = options.ropePoint?.() || { x: 0.25, y: point().y };
+				        await walk({ x: clamp(rope.x), y: point().y });
+				        let opened = false;
+				        await clip('mascotTumble', ms => {
+				          if (!opened && ms >= tune('mascotOpenAtMs')) { opened = true; openSidebar(); }
+				          const pull = ms >= tune('mascotOpenAtMs') && ms < tune('mascotReleaseAtMs');
+				          options.moveRope?.(pull ? tune('mascotRopeDownPx') : 0);
+				        });
+				        if (!opened) openSidebar();
+				        options.restoreRope?.(); defaultShow('mascot');
+				      } else if (logic === 'egg1') {
+				        await walk(edgePoint()); defaultShow('egg1Angry');
+				        await wait(tune('egg1LeadMs')); check(); await clip('eggKick'); defaultHide('egg1Angry');
+				        let thrown = false;
+				        await clip('eggFlung', async () => {
+				          if (!thrown) { thrown = true; assertResult(await client.throwPet(155, tune('egg1FlingPower'))); sidebarCall('rebound', true, 240); }
+				        });
+				        defaultShow('egg1Land'); await clip('eggLand'); defaultHide('egg1Land');
+				        openSidebar(); await wait(tune('egg1PostLandMs')); check();
+				      } else {
+				        defaultShow('egg2'); await wait(tune('egg2LeadMs')); check();
+				        let opened = false;
+				        await clip('eggHiss', (ms, duration) => {
+				          if (!opened && ms >= duration * tune('egg2OpenAtPct') / 100) { opened = true; openSidebar(); }
+				        });
+				        if (!opened) openSidebar(); defaultHide('egg2');
+				      }
+				      check();
+				      assertResult(await client.finish()); released = true;
+				      if (!gesture && ['sidebar', 'mascot'].includes(logic)) {
+				        state.phase = 'waiting';
+				        const deadline = now() + tune('holdMaxMs');
+				        while (alive() && sidebarCall('isOpen') === true && now() < deadline) await wait(100);
+				      }
+				      if (!gesture && alive() && logic !== 'egg2') {
+				        // 等待期间已归还官方唯一锁；回程重新申请，不强占用户或其他插件的新锁。
+				        assertResult(await client.begin(target)); released = false;
+				        await walk(state.home);
+				        assertResult(await client.finish()); released = true;
+				      }
+				      state.phase = 'done';
+				      return { logic, phase: 'done', busy: false };
+				    } catch (error) {
+				      if (epoch === state.epoch) {
+				        state.reason = error.message || 'official-unavailable'; state.phase = 'cancelled';
+				        if (!gesture && !released && !openedSidebar) { try { options.fallback(); } catch { /* 保留主交互。 */ } }
+				      }
+				      return { logic, phase: 'cancelled', busy: false, reason: error.message || 'official-unavailable' };
+				    } finally {
+				      if (client && !released) { client.hideBubble(); await client.finish(); }
+				      if (epoch === state.epoch) { state.busy = false; sidebarCall('commit'); options.restoreRope?.(); }
+				    }
+				  }
+				  async function warmup() {
+				    state.disposed = false;
+				    clear(state.timer); state.timer = null;
+				    const result = await probe();
+				    return result;
+				  }
+				  const snapshot = () => ({ available: state.available, reason: state.reason, busy: state.busy,
+				    phase: state.phase, logic: state.logic, target, pets: state.pets.map(item => ({ ...item })),
+				    farCount: state.farCount, nearCount: state.nearCount, home: state.home });
+				  const result = {
+				    names: PET_ANIM, warmup,
+				    dispose() { state.disposed = true; clear(state.timer); state.timer = null; cancel(); state.client?.dispose(); state.client = null; },
+				    mascot: {
+				      async tap() {
+				        if (state.busy) return { logic: 'busy', busy: true };
+				        if (!await probe()) return fallback();
+				        const p = point(), rope = options.ropePoint?.() || { x: 0.25, y: p.y };
+				        let logic = Math.abs(p.x - rope.x) < Math.abs(p.x - 1) ? 'mascot' : 'sidebar';
+				        const key = logic === 'sidebar' ? 'farCount' : 'nearCount';
+				        if (++state[key] >= tune('eggAt', logic)) { state[key] = 0; logic = logic === 'sidebar' ? 'egg1' : 'egg2'; }
+				        return run(logic);
+				      }, snapshot,
+				      registerSidebar(api) { if (!api && state.busy) cancel(); state.sidebar = api; },
+				      registerGesture(fn) { state.cancelGesture = fn; return () => { if (state.cancelGesture === fn) state.cancelGesture = null; }; },
+				      reset() { state.farCount = 0; state.nearCount = 0; },
+				    },
+				    performer: {
+				      onGrab() { return run('grab', true).then(value => value.phase === 'done'); },
+				      onPull(progress) { return Number.isFinite(progress) && progress >= 0.12 ? run('pull', true).then(value => value.phase === 'done') : Promise.resolve(false); },
+				      onRelease() { return Promise.resolve(false); }, snapshot,
+				    },
+				    tuner: {
+				      run: logic => run(logic), snapshot: () => ({ ...snapshot(), defaults: { ...PET_TUNE_DEFAULTS }, logicTuning: structuredClone(state.tuning), bubbleTiming: structuredClone(state.bubbleTiming) }),
+				      cancel,
+				      setTarget(id) {
+				        if (typeof id !== 'string' || !id.trim() || id !== id.trim() || id.length > 128 || /[\u0000-\u001f]/.test(id)) return false;
+				        cancel(); target = id; state.available = false; state.reason = 'target-changed';
+				        try { storage?.setItem(storageKey, id); } catch { /* 当前页选择仍生效。 */ }
+				        return true;
+				      },
+				      setForLogic(logic, key, value) {
+				        if (!PET_TUNER_LOGICS.includes(logic) || !(key in PET_TUNE_DEFAULTS) || !Number.isFinite(value) || value < 0 || value > 180000) return false;
+				        if (key === 'egg1FlingPower' && (value <= 0 || value > 10)) return false;
+				        if (key === 'egg2OpenAtPct' && value > 100) return false;
+				        if (key === 'eggAt' && (!Number.isInteger(value) || value < 1)) return false;
+				        state.tuning[logic] ??= {}; state.tuning[logic][key] = value; return true;
+				      },
+				      setBubbleTiming(id, config) {
+				        if (!PET_BUBBLE_SPECS.some(item => item.id === id) || !config || typeof config !== 'object') return false;
+				        for (const edge of ['show', 'hide']) {
+				          const rule = config[edge];
+				          if (rule && (!(rule.action in PET_ANIM) || !['start', 'end'].includes(rule.edge) || !Number.isFinite(rule.offsetMs) || Math.abs(rule.offsetMs) > 180000)) return false;
+				        }
+				        state.bubbleTiming[id] = structuredClone(config); return true;
+				      },
+				      reset(logic) {
+				        if (logic) {
+				          delete state.tuning[logic];
+				          for (const spec of PET_BUBBLE_SPECS.filter(item => item.logic === logic)) delete state.bubbleTiming[spec.id];
+				        } else { state.tuning = {}; state.bubbleTiming = {}; }
+				        return result.tuner.snapshot();
+				      },
+				    },
+				  };
+				  return result;
+				}
+
+		// ── 客户端正文（packages/pet-link/src/client.js）───────────────────────────────
+		/** 官方 pet 联动客户端入口；主包只消费登记门面，运行期通过本页 Cordis 服务读取实况。 */
+		const PET_LINK_HOST_REQUIRED = [
+		  'weT', 'apiUrl', 'apiFetch', 'wallSidebarOpen', 'wallSidebarClose', 'wallSidebarToggle', 'registerPetLink',
+		];
+		for (const key of PET_LINK_HOST_REQUIRED) {
+		  if (!(key in host)) throw new Error('[wallpaper-engine-pet-link] 主 bundle 键集缺少 "' + key + '"');
+		}
+		const { weT, apiUrl, apiFetch, wallSidebarOpen, wallSidebarClose, wallSidebarToggle, registerPetLink } = host;
+		let petLinkContext = null;
+		const petLink = createOfficialPetPerformer({
+		  translate: weT,
+		  getContext: () => petLinkContext,
+		  async fetchTargets() {
+		    const response = await apiFetch(apiUrl('/pet-link/official'));
+		    return response.data || { ok: false, reason: response.error || 'transport-error' };
+		  },
+		  async request(payload) {
+		    const response = await apiFetch(apiUrl('/pet-link/official'), {
+		      method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload),
+		    });
+		    return response.data || { ok: false, reason: response.error || 'transport-error' };
+		  },
+		  bubbleUrl: index => apiUrl('/pet-link/official/assets/m' + index + '.png'),
+		  ropePoint() {
+		    const rope = document.querySelector('.we-rope');
+		    const box = rope?.getBoundingClientRect();
+		    return box ? { x: (box.left + box.width / 2) / window.innerWidth, y: box.bottom / window.innerHeight } : null;
+		  },
+		  moveRope(px) {
+		    const rope = document.querySelector('.we-rope');
+		    if (rope) rope.style.setProperty('--we-rope-pull', px + 'px');
+		  },
+		  restoreRope() { document.querySelector('.we-rope')?.style.removeProperty('--we-rope-pull'); },
+		  fallback() {
+		    if (typeof wallSidebarToggle === 'function') return wallSidebarToggle('mascot') === true;
+		    if (typeof wallSidebarOpen === 'function') return wallSidebarOpen('mascot') === true;
+		    return false;
+		  },
+		});
+		const petTuner = createOfficialPetTuner(petLink, { translate: weT });
+		Object.assign(petLink.tuner, petTuner);
+		const petLinkWarmup = petLink.warmup;
+		petLink.warmup = () => { petTuner.install(); return petLinkWarmup(); };
+		const petLinkDispose = petLink.dispose;
+		petLink.dispose = () => { petTuner.dispose(); petLinkDispose(); };
+		registerPetLink(petLink);
+
+		exports.inject = [];
+		exports.apply = ctx => {
+		  petLinkContext = ctx;
+		  petLink.warmup();
+		  ctx.effect(() => () => {
+		    if (petLinkContext === ctx) { petLink.dispose(); petLinkContext = null; }
+		  });
+		};
+		if (typeof exports.apply !== "function") exports.apply = () => undefined;
+		if (!Array.isArray(exports.inject)) exports.inject = [];
+		return module.exports;
+	},
+});

package/lib/index.js

@@ -0,0 +1,34 @@
+import { registerOfficialPetRoutes } from './routes/official-pet.js';
+
+export const name = 'dsh-plugin-wallpaper-engine-pet-link';
+export const inject = ['webServer', 'wallpaperEngineHost'];
+export const routeConfigs = Object.freeze([Object.freeze({})]);
+
+/** 官方 pet 是用户独立安装的可选插件；装载时不写它的配置或资源目录。 */
+export function apply(ctx, config) {
+  const host = ctx.wallpaperEngineHost;
+  if (!host) throw new Error('[wallpaper-engine] pet-link 缺少 wallpaperEngineHost 服务');
+  const keys = host.keys('pet-link', ctx);
+  const deps = Object.freeze({ ...keys, http: host.http });
+  return keys.handOffTeardown(ctx, keys.runComponent('pet-link', ctx, config || {}, deps, applyImpl));
+}
+
+export function applyImpl(ctx, config = {}, c) {
+  const { webServer } = ctx;
+  const { base, http } = c;
+  const disposers = [];
+  let active = true;
+  const dispose = () => {
+    if (!active) return;
+    active = false;
+    for (const off of disposers.splice(0).reverse()) {
+      try { off(); } catch { /* 继续归还其余注册。 */ }
+    }
+  };
+  try {
+    registerOfficialPetRoutes(webServer, { disposers, base, http }, {
+      isLinkEnabled: () => config.linkEnabled !== false,
+    });
+  } catch (error) { dispose(); throw error; }
+  return dispose;
+}

package/lib/official-provider.js

@@ -0,0 +1,151 @@
+import { randomUUID } from 'node:crypto';
+
+const validId = value => typeof value === 'string' && value.trim() === value
+  && value.length > 0 && value.length <= 128 && !/[\u0000-\u001f]/.test(value);
+const failure = reason => ({ ok: false, reason });
+
+/** 宿主独占指令流；官方锁凭证不交给页面，旧轮只能释放自己的凭证。 */
+export function createOfficialPetCoordinator({ request, assetUrl, now = Date.now, leaseMs = 5000 }) {
+  const generation = randomUUID();
+  const runs = new Map();
+  let active = true;
+  async function call(path, options) {
+    try { return await request(path, options); }
+    catch { return failure('official-unavailable'); }
+  }
+  const current = run => active && runs.get(run.petId) === run && now() < run.expiresAt;
+  const ticket = run => ({ ok: true, generation, petId: run.petId, pageId: run.pageId,
+    runId: run.runId, expiresAt: run.expiresAt });
+  function find(input) {
+    const run = runs.get(input?.petId);
+    return run && input.generation === generation && input.runId === run.runId
+      && input.pageId === run.pageId && current(run) ? run : null;
+  }
+  async function close(run) {
+    if (runs.get(run.petId) === run) runs.delete(run.petId);
+    await run.queue;
+    if (run.lockId) return call('lock/release', { query: { pet: run.petId }, body: { lockId: run.lockId } });
+    return { ok: true };
+  }
+  function serial(run, fn) {
+    const next = run.queue.then(async () => {
+      if (!current(run)) return failure('run-lost');
+      return fn();
+    });
+    run.queue = next.then(() => undefined, () => undefined);
+    return next;
+  }
+  async function targets() {
+    if (!active) return failure('bridge-disposed');
+    const config = await call('config', { method: 'GET' });
+    if (!config || typeof config !== 'object' || config.ok === false) return failure('official-unavailable');
+    const pets = [];
+    const ids = new Set();
+    for (const group of Object.values(config)) {
+      if (!Array.isArray(group?.pets)) continue;
+      for (const pet of group.pets) {
+        if (!validId(pet?.id) || ids.has(pet.id)) return failure('invalid-pet-config');
+        ids.add(pet.id);
+        pets.push({ id: pet.id, name: typeof pet.name === 'string' ? pet.name : pet.id,
+          display: pet.display, size: pet.size });
+      }
+    }
+    return { ok: true, pets };
+  }
+  async function sweep() {
+    await Promise.all([...runs.values()].filter(run => !current(run)).map(close));
+  }
+  async function start(input) {
+    if (!active) return failure('bridge-disposed');
+    if (!validId(input?.petId) || !validId(input?.pageId)) return failure('bad-request');
+    await sweep();
+    const listed = await targets();
+    if (!listed.ok) return listed;
+    const pet = listed.pets.find(item => item.id === input.petId);
+    if (!pet) return failure('unknown-pet');
+    if (pet.display !== 'web' && pet.display !== 'both') return failure('pet-not-displayed');
+    // 查询配置后再次检查，两个并发 start 不能同时越过这道门。
+    if (!active) return failure('bridge-disposed');
+    if (runs.has(input.petId)) return failure('busy');
+    if (runs.size >= 32) return failure('bridge-busy');
+    const run = { petId: input.petId, pageId: input.pageId, runId: randomUUID(),
+      expiresAt: now() + leaseMs, lockId: '', queue: Promise.resolve() };
+    runs.set(run.petId, run);
+    const pending = call('lock', { query: { pet: run.petId, surface: 'web' }, body: { ttl: leaseMs } });
+    run.queue = pending.then(() => undefined);
+    const result = await pending;
+    if (result?.ok === true && validId(result.lockId)) run.lockId = result.lockId;
+    if (!current(run) || !run.lockId || result.petId !== run.petId
+      || !Number.isFinite(result.expiresAt) || result.expiresAt <= now()) {
+      await close(run);
+      return failure(result?.ok === false ? result.reason : 'run-lost');
+    }
+    run.expiresAt = Math.min(run.expiresAt, result.expiresAt);
+    return ticket(run);
+  }
+  async function heartbeat(input) {
+    const run = find(input);
+    if (!run) return failure('run-lost');
+    const result = await serial(run, async () => {
+      const renewed = await call('lock', { query: { pet: run.petId, surface: 'web' },
+        body: { lockId: run.lockId, ttl: leaseMs } });
+      if (!current(run)) return failure('run-lost');
+      if (renewed?.ok !== true || renewed.lockId !== run.lockId || renewed.petId !== run.petId
+        || !Number.isFinite(renewed.expiresAt) || renewed.expiresAt <= now()) {
+        return failure(renewed?.ok === false ? renewed.reason : 'invalid-lock-response');
+      }
+      run.expiresAt = Math.min(now() + leaseMs, renewed.expiresAt);
+      return ticket(run);
+    });
+    if (!result.ok) await close(run);
+    return result;
+  }
+  function commandBody(input) {
+    const action = input?.action;
+    if (action?.kind === 'anim') {
+      const url = assetUrl(action.name);
+      if (!url || !['left', 'right'].includes(action.facing)) return null;
+      return { path: 'anim', body: { url, facing: action.facing } };
+    }
+    if (action?.kind === 'position') {
+      if (![action.x, action.y].every(value => Number.isFinite(value) && value >= 0 && value <= 1)
+        || !['instant', 'line', 'spring'].includes(action.mode)) return null;
+      if (action.mode === 'line' && (!Number.isFinite(action.duration) || action.duration < 0
+        || action.duration > 180000)) return null;
+      return { path: 'position', body: { x: action.x, y: action.y, mode: action.mode,
+        ...(action.mode === 'line' ? { duration: action.duration } : {}) } };
+    }
+    if (action?.kind === 'throw' && Number.isFinite(action.angle)
+      && Number.isFinite(action.power) && action.power > 0 && action.power <= 10) {
+      return { path: 'throw', body: { angle: action.angle, power: action.power } };
+    }
+    return null;
+  }
+  async function command(input) {
+    const run = find(input);
+    if (!run) return failure('run-lost');
+    const action = commandBody(input);
+    if (!action) return failure('bad-request');
+    const result = await serial(run, async () => {
+      const response = await call(action.path, { query: { pet: run.petId, surface: 'web', lock: run.lockId },
+        body: action.body });
+      if (!current(run)) return failure('run-lost');
+      if (response?.ok !== true) return failure(response?.reason || 'invalid-action-response');
+      if (action.path === 'anim' && !validId(response.playbackId)) return failure('missing-playback-id');
+      return { ok: true, ...(action.path === 'anim' ? { playbackId: response.playbackId } : {}) };
+    });
+    if (!result.ok) await close(run);
+    return result;
+  }
+  async function finish(input) {
+    const run = find(input);
+    if (!run) return failure('run-lost');
+    const released = await close(run);
+    return released?.ok === true ? { ok: true } : failure(released?.reason || 'release-failed');
+  }
+  async function dispose() {
+    active = false;
+    await Promise.all([...runs.values()].map(close));
+  }
+  return { generation, targets, start, heartbeat, command, finish, sweep, dispose };
+}

package/lib/prepared.js

@@ -0,0 +1,10 @@
+/** 桥接专属素材名单；不包含官方 pet 的客户端、宿主或基础动画。 */
+export const PET_NAMES = Object.freeze([
+  '通用-右侧螃蟹步-dshwe', '通用-左侧螃蟹步-dshwe',
+  '侧边栏-蓄力准备往后拉-dshwe', '侧边栏-后拉接疲态结束-dshwe',
+  '吉祥物-跳抓眩晕落地起身-dshwe', '彩蛋-侧边栏-半身转向踢腿-dshwe',
+  '彩蛋-侧边栏-被弹飞-dshwe', '彩蛋-侧边栏-落地-dshwe', '彩蛋-吉祥物-哈气-dshwe',
+]);
+export const MEME_NAMES = Object.freeze([
+  '累瘫鲸鱼的两碗饭', '蓝发鲸尾女仆拒绝换壁纸', '暴怒鲸尾女仆贴纸', '吓哭了', '？！欺负一只肥鱼！？',
+]);

package/lib/routes/official-pet.js

@@ -0,0 +1,118 @@
+import { createReadStream, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createOfficialPetCoordinator } from '../official-provider.js';
+import { PET_NAMES, MEME_NAMES } from '../prepared.js';
+
+export const DEPS = ['disposers', 'base', 'http'];
+
+/** 正式官方桥接；端口来自宿主服务，不能把页面请求变成任意 URL 代理。 */
+export function registerOfficialPetRoutes(webServer, c, options = {}) {
+  const { disposers, base, http } = c;
+  const BASE = base;
+  const origin = () => {
+    const port = webServer.port;
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('官方桌宠宿主端口尚未就绪');
+    return `http://127.0.0.1:${port}`;
+  };
+  const streams = new Set();
+  const assets = new Map();
+  for (const [index, name] of PET_NAMES.entries()) {
+    assets.set(name, { path: `${BASE}/pet-link/official/assets/a${index}.webm`,
+      file: fileURLToPath(new URL(`../../assets/webm/${name}.webm`, import.meta.url)), type: 'video/webm' });
+  }
+  const images = MEME_NAMES.map((name, index) => ({ path: `${BASE}/pet-link/official/assets/m${index}.png`,
+    file: fileURLToPath(new URL(`../../assets/memes/${name}.png`, import.meta.url)), type: 'image/png' }));
+  const request = options.request || (async (path, args) => {
+    const url = new URL(`/dsh-pet-7340/${path}`, origin());
+    for (const [key, value] of Object.entries(args.query || {})) url.searchParams.set(key, value);
+    const method = args.method || 'POST';
+    const response = await fetch(url, { method, redirect: 'error', cache: 'no-store',
+      signal: AbortSignal.timeout(2500), headers: { 'Content-Type': 'application/json' },
+      ...(method === 'GET' ? {} : { body: JSON.stringify(args.body) }) });
+    if (!response.ok) throw new Error('官方接口请求失败');
+    return response.json();
+  });
+  const coordinator = createOfficialPetCoordinator({ request,
+    assetUrl: name => assets.has(name) ? origin() + assets.get(name).path : null });
+  let active = true;
+  const timer = setInterval(() => { void coordinator.sweep(); }, 1000);
+  timer.unref?.();
+  disposers.push(() => {
+    active = false;
+    clearInterval(timer);
+    for (const stream of streams) stream.destroy();
+    streams.clear();
+    void coordinator.dispose();
+  });
+  const send = (res, status, value) => http.sendJson(res, status, value);
+  const enabled = () => active && (!options.isLinkEnabled || options.isLinkEnabled());
+  disposers.push(webServer.register({ kind: 'exact', path: `${BASE}/pet-link/official`,
+    handler: async (req, res) => {
+      if (req.method !== 'GET' && req.method !== 'POST') return send(res, 405, { ok: false, reason: 'method-not-allowed' });
+      if (!enabled()) return send(res, 200, { ok: false, reason: 'bridge-disabled' });
+      if (req.method === 'GET') return send(res, 200, await coordinator.targets());
+      // 本地 API 没有认证，仍拒绝浏览器的跨站写入；不信任 Host 头构造上游地址。
+      let sameOrigin = true;
+      if (req.headers?.origin) {
+        try {
+          const from = new URL(req.headers.origin);
+          sameOrigin = from.protocol === 'http:' && Number(from.port || 80) === webServer.port
+            && ['127.0.0.1', 'localhost', '[::1]'].includes(from.hostname);
+        } catch { sameOrigin = false; }
+      }
+      if (!sameOrigin || req.headers?.['sec-fetch-site'] === 'cross-site') {
+        return send(res, 403, { ok: false, reason: 'cross-site-request' });
+      }
+      try {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of req) {
+          size += Buffer.byteLength(chunk);
+          if (size > 8192) return send(res, 413, { ok: false, reason: 'body-too-large' });
+          chunks.push(Buffer.from(chunk));
+        }
+        const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        if (!enabled()) return send(res, 200, { ok: false, reason: 'bridge-disabled' });
+        const methods = { start: coordinator.start, heartbeat: coordinator.heartbeat,
+          command: coordinator.command, finish: coordinator.finish };
+        if (!Object.hasOwn(methods, input?.op)) return send(res, 400, { ok: false, reason: 'bad-request' });
+        return send(res, 200, await methods[input.op](input));
+      } catch { return send(res, 400, { ok: false, reason: 'bad-request' }); }
+    } }));
+  const assetPaths = new Map([...assets.values(), ...images].map(asset => [asset.path, asset]));
+  disposers.push(webServer.register({ kind: 'prefix', path: `${BASE}/pet-link/official/assets/`, handler: (req, res) => {
+       const asset = assetPaths.get(new URL(req.url, 'http://localhost').pathname);
+       if (!asset) { res.statusCode = 404; res.end(); return; }
+      if (req.method !== 'GET' && req.method !== 'HEAD') { res.statusCode = 405; res.end(); return; }
+      if (!active) { res.statusCode = 410; res.end(); return; }
+      try {
+        const { size } = statSync(asset.file);
+        const range = req.headers?.range;
+        let start = 0;
+        let end = size - 1;
+        if (range) {
+          const match = /^bytes=(\d*)-(\d*)$/.exec(range);
+          if (match && (match[1] || match[2])) {
+            if (match[1]) { start = Number(match[1]); end = match[2] ? Math.min(Number(match[2]), end) : end; }
+            else start = Math.max(0, size - Number(match[2]));
+          } else start = -1;
+          if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || start > end || start >= size) {
+            res.statusCode = 416; res.setHeader('Content-Range', `bytes */${size}`); res.end(); return;
+          }
+        }
+        res.statusCode = range ? 206 : 200;
+        res.setHeader('Content-Type', asset.type);
+        res.setHeader('Accept-Ranges', 'bytes');
+        res.setHeader('Content-Length', end - start + 1);
+        if (range) res.setHeader('Content-Range', `bytes ${start}-${end}/${size}`);
+        if (req.method === 'HEAD') { res.end(); return; }
+        const stream = createReadStream(asset.file, { start, end });
+        streams.add(stream);
+        stream.on('error', () => res.destroy());
+        stream.on('close', () => streams.delete(stream));
+        res.on('close', () => stream.destroy());
+        stream.pipe(res);
+      } catch { res.statusCode = 404; res.end(); }
+     } }));
+  return coordinator;
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Pet Link",
+    "description": "Optional pet interactions, a tuning panel, hot-plug lifecycle and explicit bridge preparation; never installs dsh-pet automatically."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "桌宠联动",
+    "description": "可选桌宠联动：四条演出、维护调参面板、热插拔及显式桥接准备；不自动安装桌宠。"
+  }
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "dsh-plugin-wallpaper-engine-pet-link",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.4.0",
+  "description": "Optional official dsh-pet bridge: public API control, four interaction sequences and independent page bubbles; no bundled pet or patching.",
+  "icon": "./icon.png",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.pet-link.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": ["@deepseek-ai/dsh-client-runtime"],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "files": ["lib/", "cordis.patch.yml", "locale/", "icon.png", "package.json", "assets/"],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-host-webserver": ">=0.1.5-rc.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
+}