dsh-pet-live2d 2.3.3 → 3.0.0

package/lib/client.js

@@ -37,6 +37,124 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
   const MIN_SIZE = 160;
   const MAX_SIZE = 760;
   const DEFAULT_SIZE = 300;
+  /** 显示层轮询间隔：桌面端接管/让位要在一秒内被看见。 */
+  const LAYER_POLL_MS = 1000;
+
+  /**
+   * 桌面端注册进来的"跟随处理器"。
+   *
+   * 为什么需要这条通道：`pointermove` 只在指针**落在窗口内**时才由浏览器送来 —— 用户在
+   * 别的程序里动鼠标时，落点不在我们这个窗口上，页面**一个事件都收不到**（全屏透明层也
+   * 帮不上忙：事件不是被挡住，而是压根没发生在这个窗口上）。
+   *
+   * 而壳本来就在**每 33ms 读一次全局光标**（穿透判定必须知道指针在哪，见它的 hover 循环），
+   * 所以把那个坐标顺手喂进来就够了 —— 不需要新的轮询，也不需要原生鼠标钩子。
+   */
+  const externalPointer = { handler: null, lastX: null, lastY: null };
+
+  /**
+   * 壳调用的入口：`window.__petPointer(x, y)`（`clientX/clientY`，逻辑像素）。
+   *
+   * 位置没变就什么都不做 —— 壳 33ms 喂一次，光标的静止不该被当成"一直在动"。
+   */
+  function applyExternalPointer(clientX, clientY) {
+    if (!Number.isFinite(clientX) || !Number.isFinite(clientY)) return;
+    if (externalPointer.handler === null) return;
+    if (externalPointer.lastX === clientX && externalPointer.lastY === clientY) return;
+    externalPointer.lastX = clientX;
+    externalPointer.lastY = clientY;
+    externalPointer.handler(clientX, clientY);
+  }
+  if (typeof window !== "undefined") window.__petPointer = applyExternalPointer;
+
+  /**
+   * 这一份客户端跑在**哪里**。
+   *
+   * 桌面壳（`sidecar/page/runtime.js`）会建 `window.__petDesktop`，DSH 页面里没有。
+   * 让位判据必须知道这件事 —— 否则"owner === desktop"会被两边同时当成"该我显示"或
+   * "该我让位"（实测踩过：桌面端那只把自己藏了，用户看到"桌面上什么都没有"）。
+   */
+  const isDesktopShell = typeof window.__petDesktop === "object" && window.__petDesktop !== null;
+
+  /**
+   * 跟随范围的诊断快照（最近一次 pointermove 的中间量）。
+   *
+   * 挂在模块级而不是组件 ref 上：它要能被**页面外的驱动**读到（经 `__dshLive2dPet.gazeTrace()`），
+   * 而"跟随范围"这类问题最难的地方就是"看着像没反应"——量出判据与参数才有得查。
+   */
+  const gazeTrace = { current: null };
+
+  /**
+   * 显示层状态的**模块级 store**。
+   *
+   * 为什么不能放在 `Pet` 组件的 ref 里：设置页那一节（`PetSettingsBody`）渲染在**宠物组件
+   * 之外**（它挂在 DSH 设置页上），读组件内的 ref 会直接 `ReferenceError: layerRef is not
+   * defined` —— 整节设置打不开。这个坑真的踩过，而且是"宠物看着正常、只有设置页崩"的形态。
+   *
+   * 现在两个渲染者都从这里读：`Pet` 负责轮询（它本来就常驻），设置页只读 + 订阅。
+   */
+  const LAYER_INITIAL = { mode: "auto", owner: "inline", desktopRunning: false, binary: null, download: null, at: 0 };
+  const layerStore = { value: LAYER_INITIAL, listeners: new Set() };
+  const setLayerState = (next) => {
+    const merged = Object.assign({}, layerStore.value, next);
+    if (merged.mode === layerStore.value.mode
+      && merged.owner === layerStore.value.owner
+      && merged.desktopRunning === layerStore.value.desktopRunning
+      && merged.binary === layerStore.value.binary
+      && merged.download === layerStore.value.download) return;
+    layerStore.value = merged;
+    for (const listener of layerStore.listeners) {
+      try { listener(merged); } catch { /* 一个订阅者坏了不该拖垮别的 */ }
+    }
+  };
+  /** 订阅显示层状态（返回当前值）。 */
+  function useLayerState() {
+    const [value, setValue] = useState(layerStore.value);
+    useEffect(() => {
+      const listener = (next) => setValue(next);
+      layerStore.listeners.add(listener);
+      // 订阅之前可能已经变了：补一次当前值。
+      listener(layerStore.value);
+      return () => { layerStore.listeners.delete(listener); };
+    }, []);
+    return value;
+  }
+
+  /**
+   * **谁在轮询**：一个模块级单例，**不跟着任何组件走**。
+   *
+   * 原来轮询写在 `Pet` 的 effect 里 —— 那有个要命的缺口：**用户在设置里选了"桌面"之后，
+   * 页面里那只会让位（`visibility: hidden`），而设置页那一行要显示的正是"桌面端在跑"**。
+   * 可设置页只订阅、不轮询，所以它等到的是"页面那只还活着时的最后一次结果"，文本就停在
+   * "二进制不在"不动；只有重新打开设置页（重新挂载、读到 store 的当前值）才对。
+   *
+   * 换句话说：这个功能的观测者不能是它要观测的那个东西。轮询挪到模块级，页面里那只在不在
+   * 都照轮（它本来就是每秒一次 GET，代价可以忽略）。
+   */
+  let layerPollStarted = false;
+  let layerPollTimer = 0;
+  function ensureLayerPolling() {
+    if (layerPollStarted) return;
+    layerPollStarted = true;
+    const poll = async () => {
+      try {
+        const response = await fetch(API + "/layer", { cache: "no-store" });
+        const payload = await response.json();
+        setLayerState({
+          mode: typeof payload?.mode === "string" ? payload.mode : "auto",
+          owner: payload?.owner === "desktop" ? "desktop" : "inline",
+          desktopRunning: payload?.desktopRunning === true,
+          binary: payload?.binary ?? null,
+          download: payload?.download ?? null,
+          at: Date.now(),
+        });
+      } catch {
+        /* DSH 那边的路由还没挂上、或页面刚起来：下一轮再问 */
+      }
+      layerPollTimer = window.setTimeout(poll, LAYER_POLL_MS);
+    };
+    poll();
+  }
 
   // -------------------------------------------------- motion controller
   //
@@ -175,6 +293,17 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
      * different from the idle loop.
      */
     let settled = false;
+    /**
+     * **反应跑完之后要回到哪个动作**（`{group, index, options}`，`null` = 回待机）。
+     *
+     * 由来：摸头 / 摸尾巴是一段"临时表演"，但它结束时 `finishAction` 会 `playIdle()` ——
+     * 于是用户刚选好的槽位动作（掏出手机 / 吹泡泡糖）**被整个还原**掉了
+     * （用户报的"摸头和摸尾巴不要还原当前动作啊"）。
+     *
+     * 这里记住"开演之前她在演什么"，反应一结束就把它接回去。接的时候用的是**同一个选项**
+     * （`persist`/`hold` 原样带过去），所以举着的手还是举着、泡还是那个泡。
+     */
+    let resumeAfterAction = null;
     /** Downsampled opacity grid of the rendered character (null = unknown). */
     let hitMask = null;
     /** The stage-local box the grid spans (the model's bounding box). */
@@ -287,6 +416,8 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     /** 由 parts 解出来的 drawable 下标（换模型要重算，缓存起来）。 */
     let headIndices = null;
     let tailIndices = null;
+    /** 尾巴类里**贴图落在尾鳍区域**的那几块（收窄结果，换模型要重算）。 */
+    let tailFinIndices = null;
 
     /**
      * 部件 id → drawable 下标（带所属部件下标）：cdi3 的部件名 → 引擎原始表。
@@ -434,6 +565,170 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       return read ? false : null;
     };
 
+    /**
+     * 一块 drawable 的**纹理坐标**包围盒（归一化 0..1），读不到返回 null。
+     *
+     * 为什么需要它：这只宠物有十几个"尾巴/翅膀"配件，几何同时留在原地 —— 光看几何
+     * 分不出谁是谁。而**贴图是作者自己画的**：鲸鱼尾鳍那块贴图区域只属于尾巴。
+     * 有了 UV 就能回答"这块 drawable 画的是贴图上哪一块"，那是权威依据。
+     *
+     * 字段名各版本不一（`vertexUvs` / `uvs`），所以按候选顺序试。
+     */
+    const readUvs = (index) => {
+      const raw = model?.internalModel?.coreModel?._model;
+      const drawables = raw?.drawables;
+      if (drawables === undefined || drawables === null) return null;
+      let table;
+      for (const key of ["vertexUvs", "uvs", "drawableVertexUvs"]) {
+        const candidate = drawables[key];
+        if (candidate !== undefined && candidate !== null) { table = candidate; break }
+      }
+      if (table === undefined) return null;
+      const entry = table[index];
+      if (entry === undefined || entry === null) return null;
+      const values = Array.from(entry);
+      if (values.length < 2) return null;
+      let minU = Infinity;
+      let minV = Infinity;
+      let maxU = -Infinity;
+      let maxV = -Infinity;
+      for (let i = 0; i + 1 < values.length; i += 2) {
+        const u = values[i];
+        const v = values[i + 1];
+        if (u < minU) minU = u;
+        if (u > maxU) maxU = u;
+        if (v < minV) minV = v;
+        if (v > maxV) maxV = v;
+      }
+      return { minU, minV, maxU, maxV };
+    };
+
+    /**
+     * 尾巴判定**此刻**该用哪几块 drawable（带缓存）。
+     *
+     * 名字里带尾/翅的部件有 15 个 / 16 块，其中 11 块是可换配件的几何、**一直留在原地**、
+     * 横跨从头顶到腰腹的整个角色。全算上的话"算尾巴"的格子占角色 22%，其中 86.6% 同时
+     * 算头 —— 而路由是摸头优先，于是**可见的尾鳍永远轮不到**（用户报的"摸尾巴很难点到"）。
+     *
+     * 收窄依据是**贴图**（作者自己画的）：只留 UV 落在尾鳍区域的那几块（`TAIL_FIN_UV`）。
+     * 保守之处：UV 读不到、或者收完一块不剩，就退回原来那一整份 —— 宁愿判定偏松，
+     * 也不能让"摸尾巴"整个消失。
+     */
+    const tailIndicesNow = () => {
+      if (tailIndices === null) tailIndices = drawableIndicesForParts(tailParts);
+      if (tailFinIndices === null) {
+        const narrowed = (tailIndices ?? []).filter((entry) => uvInsideTailFin(readUvs(entry.index)) === true);
+        tailFinIndices = narrowed.length > 0 ? narrowed : (tailIndices ?? []);
+      }
+      return tailFinIndices;
+    };
+
+    /**
+     * 尾巴类 drawable 此刻的**并集包围盒**（模型空间），读不到返回 null。
+     *
+     * 两处用：① `hitsMask` 把它并进"算不算落在她身上"（尾鳍摆出静态轮廓网格之外时，
+     * 那一瞬间的点击不该落空）；② `[data-hit]` 的 `clip-path` 里拼进去的那块矩形
+     * （跟着摆动重建，见 hitPath）。
+     */
+    const measureTailBox = () => {
+      const list = tailIndicesNow();
+      const im = model?.internalModel;
+      if (list.length === 0 || im === null || im === undefined) return null;
+      const box = { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity };
+      for (const entry of list) {
+        let index = entry.index;
+        if (typeof entry.id === "string" && typeof im.getDrawableIndex === "function") {
+          const fresh = im.getDrawableIndex(entry.id);
+          if (fresh >= 0) index = fresh;
+        }
+        let verts;
+        try {
+          verts = im.getDrawableVertices(index);
+        } catch {
+          continue;
+        }
+        if (verts === undefined || verts === null || verts.length < 2) continue;
+        for (let i = 0; i + 1 < verts.length; i += 2) {
+          const vx = verts[i];
+          const vy = verts[i + 1];
+          if (vx < box.minX) box.minX = vx;
+          if (vx > box.maxX) box.maxX = vx;
+          if (vy < box.minY) box.minY = vy;
+          if (vy > box.maxY) box.maxY = vy;
+        }
+      }
+      return box.maxX > box.minX && box.maxY > box.minY ? box : null;
+    };
+
+    /**
+     * 模型空间 → **舞台局部**坐标（CSS px），读不到返回 null。
+     *
+     * 为什么不用引擎的 `toStagePosition()`：这个包装层上没有它（实测直接抛异常，
+     * 外面只看到 null）。改用**两个盒子对齐**：`model.getBounds()` 给的是模型在舞台上的
+     * 轴对齐盒，而模型空间里"整只宠物的盒"由全部 drawable 的顶点算出来。两者一比就是
+     * 缩放 + 平移（模型的旋转是 0，锚点已经烘进 getBounds），所以这条映射在缩放、
+     * 拖动、窗口 resize 之后都成立，也不依赖任何私有字段。
+     */
+    const modelToStage = (x, y) => {
+      const im = model?.internalModel;
+      if (model === null || im === null || im === undefined) return null;
+      if (typeof im.getDrawableIDs !== "function" || typeof im.getDrawableVertices !== "function") return null;
+      let bounds;
+      try {
+        bounds = model.getBounds();
+      } catch {
+        return null;
+      }
+      if (bounds === undefined || bounds === null || !(bounds.width > 0) || !(bounds.height > 0)) return null;
+      let minX = Infinity;
+      let minY = Infinity;
+      let maxX = -Infinity;
+      let maxY = -Infinity;
+      try {
+        for (const id of im.getDrawableIDs()) {
+          const index = im.getDrawableIndex(String(id));
+          if (index < 0) continue;
+          const verts = im.getDrawableVertices(index);
+          if (verts === undefined || verts === null) continue;
+          for (let i = 0; i + 1 < verts.length; i += 2) {
+            if (verts[i] < minX) minX = verts[i];
+            if (verts[i] > maxX) maxX = verts[i];
+            if (verts[i + 1] < minY) minY = verts[i + 1];
+            if (verts[i + 1] > maxY) maxY = verts[i + 1];
+          }
+        }
+      } catch {
+        return null;
+      }
+      if (!(maxX > minX) || !(maxY > minY)) return null;
+      return {
+        x: bounds.x + (x - minX) / (maxX - minX) * bounds.width,
+        y: bounds.y + (y - minY) / (maxY - minY) * bounds.height,
+      };
+    };
+
+    /** 静态快照网格的判定（`hitsMask` 与诊断读口共用一份实现，避免两处走岔）。 */
+    const hitsMaskGrid = (x, y, width, height) => {
+      if (hitMask === null) return true;
+      if (width <= 0 || height <= 0) return true;
+      // The grid covers the model's own bounding box, so normalise against
+      // that box rather than the whole stage.
+      const box = hitBox ?? { x: 0, y: 0, width, height };
+      const gx = Math.floor(((x - box.x) / box.width) * hitMask.width);
+      const gy = Math.floor(((y - box.y) / box.height) * hitMask.height);
+      // One cell of tolerance: the model breathes and sways, so requiring an
+      // exact opaque cell would make edge clicks feel unreliable.
+      for (let dy = -1; dy <= 1; dy += 1) {
+        for (let dx = -1; dx <= 1; dx += 1) {
+          const cx = gx + dx;
+          const cy = gy + dy;
+          if (cx < 0 || cy < 0 || cx >= hitMask.width || cy >= hitMask.height) continue;
+          if (hitMask.data[cy * hitMask.width + cx] === 1) return true;
+        }
+      }
+      return false;
+    };
+
     /** 点 (x,y) 在 verts 的第 i0/i1/i2 号顶点组成的三角形里吗（同向叉积法）。 */
     const pointInTriangle = (x, y, verts, i0, i1, i2) => {
       const ax = verts[i0 * 2];
@@ -582,6 +877,18 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     const expressionFade = new Map();
     /** 上一帧的时间戳（算 dt 用）；0 表示还没有基准。 */
     let expressionFadeAt = 0;
+    /**
+     * 尾巴类 drawable 的**实时并集包围盒**（模型空间）与它的采样时刻。
+     *
+     * 尾鳍一直在摆，而可点击的轮廓遮罩是开机抓一次的静态网格 —— 摆到网格之外的那一瞬，
+     * "点在尾巴上"会被判成"没落在她身上"。所以每帧（节流 100ms）采一次这个盒子，
+     * `hitsMask` 把它一起算进去：**尾巴摆到哪儿都算她**。
+     *
+     * 采样放在 saveParameters 缝里（`update()` 之前）—— 那是这一帧真正要画的姿势，
+     * 帧外读到的是引擎基线，会慢半拍。
+     */
+    let tailBoxLive = null;
+    let tailBoxSampledAt = 0;
     /** The core model whose saveParameters hook is installed. */
     let hookedCore = null;
     /**
@@ -742,13 +1049,31 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
      * 把"别的槽位还选着的动作"的姿势写回去 —— 右手拿着手机的同时嘴部吹泡泡糖。
      *
      * 写在 applyRelease **之后**（否则会被还原表顶掉），表达式层之前（表情仍然最大）。
+     *
+     * ⚠️ **动作驱动的参数不能被保姿势录像压住**（这一条修的是用户报的"装扮里的自拍右手不抬"）：
+     * 自拍（`Selfie`）驱动 `phone5`（抬手；干净试验台实测：推 `phone5` 会让
+     * `看手机/ArtMesh26` 那块几何变形），但「掏出手机」定格时录下的那一帧里 `phone5=0`，
+     * 于是这一层每帧把它写回 0 —— 写在动作更新之后，**曲线被压住**。干净环境实测：
+     * 自拍里 `phone5` 涨到 9.713，而手那块几何一动不动（盒完全相同）。
+     *
+     * 判据**由宠物声明**（`motionOptions.<组>.ignoreKeptParams`），不在这里猜：
+     * 我试过"`currentEntry.params` 里有的就跳过"，那是**宿主按曲线生成的清单**，
+     * 可能含动作文件根本没写的参数（实测 `OpenCase` 的清单含 `phone5`，曲线却不写它）——
+     * 结果把相位/别的槽位那套保姿势一起打断了（`cdp-head`「no single hand option
+     * dominates」、`cdp-host-events`「tool phase sustains」当场红，A/B 撤回那一处即全绿）。
+     * 声明式的名单面窄、看得见、改 pet.json 就能调，不会误伤别的路径。
      */
     const applyKeptPoses = (core, values) => {
       if (keptPoses.length === 0 || values === null) return;
+      const skip = currentEntry === null
+        ? null
+        : optionsFor(currentEntry.group)?.ignoreKeptParams ?? null;
+      const skipSet = Array.isArray(skip) ? new Set(skip) : null;
       for (const group of keptPoses) {
         const frame = poseSnapshots.get(group);
         if (frame === undefined) continue;
         for (const id of Object.keys(frame)) {
+          if (skipSet !== null && skipSet.has(id)) continue;
           const at = parameterIndex(core, id);
           if (at >= 0) values[at] = frame[id];
         }
@@ -1026,6 +1351,16 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
           const probeAt = probeId === null || values === null ? -1 : parameterIndex(core, probeId);
           const pre = probeAt >= 0 ? values[probeAt] : null;
           applyExpressionLayers(core);
+          // 尾巴的实时盒子（节流）：可点区域要跟着摆动的尾鳍走，见 tailBoxLive 的注释。
+          const nowMs = typeof performance !== "undefined" && typeof performance.now === "function"
+            ? performance.now()
+            : Date.now();
+          if (nowMs - tailBoxSampledAt >= TAIL_BOX_SAMPLE_MS) {
+            tailBoxSampledAt = nowMs;
+            // 私有函数，不是公开读口 `tailBoxNow()` —— 后者挂在 api 对象上，
+            // 控制器内部看不到它（这个错误每帧抛一次，外面只表现为"盒子一直是 null"）。
+            tailBoxLive = measureTailBox();
+          }
           // The layers are now in place and update() is next, so this is the
           // pose the frame is about to draw.
           if (values !== null) {
@@ -1309,6 +1644,14 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         }, ACTION_HOLD_MAX_MS);
         return;
       }
+      // **把开演之前的动作接回去**（摸头/摸尾巴是一段临时表演，不该把用户的槽位动作还原）。
+      // 检查顺序放在最后：`hold` 那条分支自己会 park（槽位动作在演），不需要接。
+      if (resumeAfterAction !== null) {
+        const resume = resumeAfterAction;
+        resumeAfterAction = null;
+        // 相位在这期间接管了就不接：相位优先，接了会跟它抢身体。
+        if (sustainPhase === null && playOnce(resume.group, resume.index, resume.options)) return;
+      }
       playIdle();
     };
 
@@ -1525,6 +1868,11 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         headBox = null;
         hitMask = null;
         hitBox = null;
+        tailBoxLive = null;
+        tailBoxSampledAt = 0;
+        tailIndices = null;
+        tailFinIndices = null;
+        headIndices = null;
       },
       playIdle,
       playOnce,
@@ -1672,9 +2020,36 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
        * Passing the normalized offset straight to the focus controller keeps the
        * magnitude, so the gaze is proportional to how far the pointer actually is.
        */
-      updatePointer(x, y, width, height) {
+      /**
+       * 把"指针相对她中心的偏移"翻成注视方向。
+       *
+       * 接口是**偏移量**（`dx/dy` 相对她中心）加**满偏半径**（`rangePx`），不是"指针坐标 +
+       * 一个假盒子"。早先的写法是 `(x, y, width, height)`、内部拿 `width/2` 当中心，
+       * 而调用方给的是**视口坐标** —— 两个坐标系混在一句话里，结果 `nx` 恒为满偏（实测：
+       * 她中心 2386 配 width 640，`(2386-320)/320` 直接夹到 1）。实参读口一打出来就露了。
+       *
+       * 现在偏移归偏移、半径归半径，`rangePx` 就是"离她多远算看到最边上"。桌面端与网页端
+       * 共用这一条，差别只在调用方给的半径。
+       */
+      /**
+       * 把"指针相对她中心的偏移"翻成注视方向。
+       *
+       * 接口是**偏移量**（`dx/dy` 相对她中心）加**满偏半径**（`rangePx`），不是"指针坐标 +
+       * 一个假盒子"。早先的写法是 `(x, y, width, height)`、内部拿 `width/2` 当中心，
+       * 而调用方给的是**视口坐标** —— 两个坐标系混在一句话里，结果 `nx` 恒为满偏（实测：
+       * 她中心 2386 配 width 640，`(2386-320)/320` 直接夹到 1）。实参读口一打出来就露了。
+       *
+       * **偏转强度用圆形范数**：两根轴同一个半径，合成长度压到 1 以内 —— 等距线是正圆。
+       * （试过椭圆：竖直方向更宽容，但用户明确要正圆，而且"远近"本来就该由**一个**半径
+       * 决定，多一个竖直半径只是多一个要调的旋钮。）
+       */
+      updatePointer(dx, dy, rangePx) {
         if (model === null) return;
-        const half = { x: Math.max(1, width / 2), y: Math.max(1, height / 2) };
+        const range = Math.max(40, Number.isFinite(rangePx) ? rangePx : 320);
+        // 诊断：把**进函数的实参**记下来（算错与传错是两回事，只看结果分不出来）。
+        gazeTrace.current = Object.assign(gazeTrace.current ?? {}, {
+          callIn: { dx: Math.round(dx), dy: Math.round(dy), range: Math.round(range) },
+        });
         const shape = (value) => {
           // A small dead zone, so hand tremor near the centre does not make the
           // eyes wander, and a linear ramp beyond it up to full deflection.
@@ -1683,9 +2058,13 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
           const t = Math.min(1, (size - TUNING.gazeDeadzone) / (1 - TUNING.gazeDeadzone));
           return value < 0 ? -t : t;
         };
-        const nx = shape((x - half.x) / half.x);
-        // Screen y grows downward; the controller wants up-positive.
-        const ny = shape((y - half.y) / half.y);
+        const shapedX = shape(dx / range);
+        const shapedY = shape(dy / range);
+        // 圆形范数：按"到她的距离"压合成长度，方向保留 —— 等距线是正圆。
+        const norm = Math.hypot(shapedX, shapedY);
+        const scale = norm > 1 ? 1 / norm : 1;
+        const nx = shapedX * scale;
+        const ny = shapedY * scale;
         gazeTarget = { x: nx, y: ny };
         // How far the pointer is, on the SAME normalized scale the gaze uses, so
         // the mouth and the eyes agree about how far away it is.
@@ -1730,6 +2109,10 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       }),
       /** Diagnostic: the normalized gaze target the pointer last produced. */
       gazeTarget: () => gazeTarget,
+      /** Diagnostic: 最近一次 pointermove 的跟随判据（舞台尺寸 / 满偏半径 / 是否算"在看"）。 */
+      gazeTrace: () => gazeTrace.current,
+      /** Diagnostic: 当前生效的可调项快照（排查"改了没生效"时先看它）。 */
+      tuning: () => Object.assign({}, TUNING),
       /**
        * 别的槽位还选着动作时，替它们保住姿势（见 keptPoses 的注释）。
        *
@@ -1743,6 +2126,27 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       },
       /** Diagnostic: 正在替哪些动作保姿势。 */
       keptPoseDebug: () => ({ kept: keptPoses.slice(), snapshots: Array.from(poseSnapshots.keys()) }),
+      /**
+       * **诊断专用**：把某几个参数每帧强制写成给定值（传 `null` 清除）。
+       *
+       * 用途：量"某个参数到底驱动画面上哪一块几何" —— 把它推满量程，看哪几块 drawable
+       * 在动。**不要用它当产品功能**：我上一轮拿它（和 `pin`）去"修"动作，把手机盖钉死、
+       * 手机都打不开了（用户报的）。它只该出现在探针里。
+       */
+      forceParams: (map) => {
+        forcedParams = map === null || map === undefined ? null : Object.assign({}, map);
+      },
+      /**
+       * 让下一段临时表演**跑完接回**这里给的动作（`null` = 不接，回待机）。
+       *
+       * 用途：摸头 / 摸尾巴只是一段反应，不该把用户选好的槽位动作还原掉
+       * （用户报的"摸头和摸尾巴不要还原当前动作"）。
+       */
+      resumeAfter: (plan) => {
+        resumeAfterAction = plan === null || plan === undefined ? null : plan;
+      },
+      /** Diagnostic: 现在记着要接回哪个动作。 */
+      resumeDebug: () => resumeAfterAction,
       setExpressionApplier(fn) {
         applyExpression = typeof fn === "function" ? fn : null;
       },
@@ -1849,23 +2253,35 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       hitsMask(x, y, width, height) {
         if (hitMask === null) return true;
         if (width <= 0 || height <= 0) return true;
-        // The grid covers the model's own bounding box, so normalise against
-        // that box rather than the whole stage.
-        const box = hitBox ?? { x: 0, y: 0, width, height };
-        const gx = Math.floor(((x - box.x) / box.width) * hitMask.width);
-        const gy = Math.floor(((y - box.y) / box.height) * hitMask.height);
-        // One cell of tolerance: the model breathes and sways, so requiring an
-        // exact opaque cell would make edge clicks feel unreliable.
-        for (let dy = -1; dy <= 1; dy += 1) {
-          for (let dx = -1; dx <= 1; dx += 1) {
-            const cx = gx + dx;
-            const cy = gy + dy;
-            if (cx < 0 || cy < 0 || cx >= hitMask.width || cy >= hitMask.height) continue;
-            if (hitMask.data[cy * hitMask.width + cx] === 1) return true;
+        // "落点算不算落在她身上"必须与 **DOM 那一层完全一致**，否则两种坏法都会出现：
+        // 事件能进来而判定说不在她身上（点了没反应），或者判定说有而事件进不来（穿透错）。
+        // DOM 的 `clip-path` = 静态快照 + **尾巴当前那块矩形**，所以这里也就这两样：
+        //   ① 尾巴当前盒子（`measureTailBox`，当前姿势）—— 尾鳍摆出快照时靠它接住；
+        //   ② 开机抓的静态轮廓快照（下面那张网格 + 一格容差）。
+        //
+        // **不能**把头/尾的"几何"算进来：几何比像素宽，"只有几何、没有像素"的点会被判定
+        // 说成在她身上，而 DOM 那层并不覆盖它 —— cdp-passthrough 立刻红（character click
+        // 落到 page，实测）。头/尾几何是给**路由**用的（决定演什么），不是给"在不在她身上"。
+        if (model !== null && vendor !== null) {
+          try {
+            const point = model.toModelPosition(new vendor.Point(x, y));
+            const tailNow = measureTailBox();
+            if (tailNow !== null
+              && point.x >= tailNow.minX && point.x <= tailNow.maxX
+              && point.y >= tailNow.minY && point.y <= tailNow.maxY) return true;
+          } catch {
+            /* 换算失败就只按网格 */
           }
         }
-        return false;
+        return hitsMaskGrid(x, y, width, height);
       },
+      /**
+       * Diagnostic: 只按**开机抓的静态快照**那张网格判定（不含几何、不含尾巴实时盒子）。
+       *
+       * "尾鳍摆出快照"这件事没法凭空断言 —— 要证明"这一点在快照外、却在宽限之内"，
+       * 就得能把两层分开读。它只用于测试与排查，不参与行为。
+       */
+      hitsMaskStatic: (x, y, width, height) => hitsMaskGrid(x, y, width, height),
       /** Head-part ids, pushed in by the component once the catalog is ready. */
       setHeadParts(ids) {
         headParts = Array.isArray(ids) ? ids.filter((id) => typeof id === "string") : [];
@@ -1876,7 +2292,122 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       setTailParts(ids) {
         tailParts = Array.isArray(ids) ? ids.filter((id) => typeof id === "string") : [];
         tailIndices = null;
+        tailFinIndices = null;
+      },
+      /**
+       * 尾巴类 drawable 此刻的**并集包围盒**（模型空间），读不到返回 null。
+       *
+       * 用途：`hitsMask` 把它并进"算不算落在她身上"。轮廓遮罩是开机抓一次的静态网格，
+       * 而尾鳍一直在摆 —— 摆动幅度大的时候，尾鳍会摆到网格之外，那一瞬间"点在尾巴上"
+       * 会被判成"没落在她身上"，事件落空。并把集盒之后，尾巴摆到哪儿都算她。
+       */
+      tailBoxNow: () => measureTailBox(),
+      /**
+       * 尾巴这一层要画的形状：**按轮廓那套栅格重采一遍**（舞台局部像素矩形），读不到返回 null。
+       *
+       * 为什么不是"包围盒 / 凸包 / 逐块矩形"（三种都试过）：那些都是**几何并集**，而
+       * `hitsMask` 用的静态轮廓是**栅格**（还是"一格膨胀"的保守版）。两套几何不一致，
+       * 差集就成了"能摸到、判定却不算她"的空白区 —— 实测 14 格（网格 20×20），
+       * 而**把这一层关掉，那 14 格直接变 0**。用户看到的就是"右下角明明什么都没有却能摸"。
+       *
+       * 所以这里从**模型空间的三角面**重采一份与静态轮廓同规格的栅格：
+       *   * 落在同一个模型包络盒里（归一化方式和 `hitsMaskGrid` 完全一致）；
+       *   * 格子边长与静态轮廓同量级，于是两边的贴合程度一样；
+       *   * 输出的是矩形列表，由调用方拼成 `M x y h w v h h-w Z`（和 `maskPath()` 同形）。
+       */
+      tailRectNow: () => {
+        const list = tailIndicesNow();
+        const im = model?.internalModel;
+        if (list.length === 0 || im === null || im === undefined) return null;
+        // 目标格数：静态轮廓是 26×26 那一档；这里按包络盒的长边取 30，格子约 10px。
+        const bounds = model?.getBounds?.();
+        const envelope = bounds ?? hitBox;
+        if (envelope === undefined || envelope === null) return null;
+        const width = envelope.width;
+        const height = envelope.height;
+        if (!(width > 0) || !(height > 0)) return null;
+        const cells = 30;
+        const stepX = width / cells;
+        const stepY = height / cells;
+        const cols = Math.max(1, Math.round(width / stepX));
+        const rows = Math.max(1, Math.round(height / stepY));
+        const solid = new Uint8Array(cols * rows);
+        const toStage = (x, y) => modelToStage(x, y);
+        for (const entry of list) {
+          let index = entry.index;
+          if (typeof entry.id === "string" && typeof im.getDrawableIndex === "function") {
+            const fresh = im.getDrawableIndex(entry.id);
+            if (fresh >= 0) index = fresh;
+          }
+          let verts;
+          try {
+            verts = im.getDrawableVertices(index);
+          } catch {
+            continue;
+          }
+          if (verts === undefined || verts === null || verts.length < 6) continue;
+          // 逐三角面打点：每个格心落在某个三角形里就算实心。隐藏配件会"缩放成一点"，
+          // 退化三角形由 `pointInTriangle` 直接排掉（它按面积判）。
+          const count = Math.floor(verts.length / 2);
+          for (let t = 0; t + 2 < count; t += 3) {
+            let minX = Infinity;
+            let minY = Infinity;
+            let maxX = -Infinity;
+            let maxY = -Infinity;
+            for (const k of [t, t + 1, t + 2]) {
+              const vx = verts[k * 2];
+              const vy = verts[k * 2 + 1];
+              if (vx < minX) minX = vx;
+              if (vx > maxX) maxX = vx;
+              if (vy < minY) minY = vy;
+              if (vy > maxY) maxY = vy;
+            }
+            if (!(maxX > minX) || !(maxY > minY)) continue;
+            const gx0 = Math.max(0, Math.floor(((minX - envelope.x) / width) * cols) - 1);
+            const gx1 = Math.min(cols - 1, Math.ceil(((maxX - envelope.x) / width) * cols) + 1);
+            const gy0 = Math.max(0, Math.floor(((minY - envelope.y) / height) * rows) - 1);
+            const gy1 = Math.min(rows - 1, Math.ceil(((maxY - envelope.y) / height) * rows) + 1);
+            for (let gy = gy0; gy <= gy1; gy += 1) {
+              for (let gx = gx0; gx <= gx1; gx += 1) {
+                if (solid[gy * cols + gx] === 1) continue;
+                const px = envelope.x + ((gx + 0.5) / cols) * width;
+                const py = envelope.y + ((gy + 0.5) / rows) * height;
+                if (pointInTriangle(px, py, verts, t, t + 1, t + 2) === true) solid[gy * cols + gx] = 1;
+              }
+            }
+          }
+        }
+        // 实心格 → 舞台局部矩形（外扩 1px 抵挡 120ms 的摆动采样差；静态轮廓那边也有一格膨胀，
+        // 量的口径一致）。相邻格各自成矩形没关系：`clip-path` 是并集。
+        const rects = [];
+        for (let gy = 0; gy < rows; gy += 1) {
+          for (let gx = 0; gx < cols; gx += 1) {
+            if (solid[gy * cols + gx] !== 1) continue;
+            const x0 = envelope.x + (gx / cols) * width;
+            const y0 = envelope.y + (gy / rows) * height;
+            const x1 = envelope.x + ((gx + 1) / cols) * width;
+            const y1 = envelope.y + ((gy + 1) / rows) * height;
+            const a = toStage(x0, y0);
+            const b = toStage(x1, y1);
+            if (a === null || b === null) continue;
+            rects.push({
+              x0: Math.min(a.x, b.x) - 1,
+              y0: Math.min(a.y, b.y) - 1,
+              x1: Math.max(a.x, b.x) + 1,
+              y1: Math.max(a.y, b.y) + 1,
+            });
+          }
+        }
+        return rects.length === 0 ? null : rects;
       },
+      /**
+       * 模型空间 → **舞台局部**坐标（CSS px），读不到返回 null。
+       *
+       * 就是 `hitsHead / hitsTail / hitsMask` 里那条映射的逆向（它们用
+       * `model.toModelPosition()`）：用来把"尾巴此刻的包围盒"画到 DOM 上，
+       * 做成那一层跟着摆动走的可点区域。
+       */
+      modelToStage: (x, y) => modelToStage(x, y),
       idleName: () => idleName,
       groups: () => groups,
       /** Declared playback policy for one motion group (diagnostics). */
@@ -1913,22 +2444,119 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
           return true;
         }
       },
+      /**
+       * 诊断：把**尾巴类** drawable 的**当前三角面**吐出来（模型空间）。
+       *
+       * 用来看"收窄前那一整份"里每块的几何落在哪儿（收窄结果见 `tailDebug()`）——
+       * 正是靠它量出"16 块里 11 块是配件、横跨整个角色"，才决定按贴图收窄。
+       *
+       * 单位是模型空间（`toModelPosition` 的坐标系）；配合 `fitBox()` 能换算回屏幕。
+       */
+      tailDrawables: () => {
+        const list = drawableIndicesForParts(tailParts);
+        if (list === null) return [];
+        const out = [];
+        for (const entry of list) {
+          let index = entry.index;
+          if (typeof entry.id === "string" && typeof model?.internalModel?.getDrawableIndex === "function") {
+            const fresh = model.internalModel.getDrawableIndex(entry.id);
+            if (fresh >= 0) index = fresh;
+          }
+          const row = { id: entry.id, index };
+          try {
+            const verts = model.internalModel.getDrawableVertices(index);
+            let minX = Infinity;
+            let minY = Infinity;
+            let maxX = -Infinity;
+            let maxY = -Infinity;
+            const triangles = [];
+            for (let i = 0; i + 1 < verts.length; i += 2) {
+              const vx = verts[i];
+              const vy = verts[i + 1];
+              if (vx < minX) minX = vx;
+              if (vx > maxX) maxX = vx;
+              if (vy < minY) minY = vy;
+              if (vy > maxY) maxY = vy;
+            }
+            const idx = model.internalModel.coreModel.getDrawableVertexIndices(index);
+            for (let i = 0; i + 2 < idx.length && triangles.length < 400; i += 3) {
+              triangles.push([
+                verts[idx[i] * 2], verts[idx[i] * 2 + 1],
+                verts[idx[i + 1] * 2], verts[idx[i + 1] * 2 + 1],
+                verts[idx[i + 2] * 2], verts[idx[i + 2] * 2 + 1],
+              ]);
+            }
+            const uvs = readUvs(index);
+            Object.assign(row, {
+              vertices: verts.length / 2,
+              triangles: triangles.length,
+              box: { minX, minY, maxX, maxY },
+              tris: triangles,
+              // 纹理坐标（归一化）：用来回答"这块在贴图的哪一块上" —— 贴图才是
+              // "哪些部件真的是尾巴"的权威（作者自己画的图）。
+              uvBox: uvs === null ? null : uvs,
+            });
+          } catch (error) {
+            row.error = String(error?.message ?? error);
+          }
+          out.push(row);
+        }
+        return out;
+      },
+      /** 诊断：某块 drawable 的**原始 UV 数字**（不做任何换算，看表本身的形状）。 */
+      uvRaw: (index = 0) => {
+        const raw = model?.internalModel?.coreModel?._model;
+        const table = raw?.drawables?.vertexUvs;
+        if (table === undefined) return null;
+        const entry = table[index];
+        return entry === undefined ? null : Array.from(entry).slice(0, 16);
+      },
+      /** 诊断：core 里所有和 UV 有关的表名（不同版本字段名不一样，先看有什么）。 */
+      uvTables: () => {
+        const raw = model?.internalModel?.coreModel?._model;
+        if (raw === undefined) return null;
+        const out = {};
+        for (const scope of ["drawables", "parts"]) {
+          const table = raw[scope];
+          if (table === undefined || table === null) continue;
+          out[scope] = Object.keys(table);
+        }
+        out.drawableKeys = raw.drawables === undefined ? [] : Object.keys(raw.drawables);
+        return out;
+      },
+      /** 诊断：模型自绘包围盒（模型空间）与舞台尺寸，供"模型空间 → 屏幕"换算。 */
+      fitBox: () => {
+        try {
+          const b = model.getBounds();
+          return {
+            model: { x: b.x, y: b.y, width: b.width, height: b.height },
+            scale: typeof model.scale?.x === "number" ? model.scale.x : null,
+            position: { x: model.position?.x ?? null, y: model.position?.y ?? null },
+            anchor: { x: model.anchor?.x ?? null, y: model.anchor?.y ?? null },
+          };
+        } catch {
+          return null;
+        }
+      },
       /** Diagnostic: the measured head box in model space, or null. */
       headBox: () => headBox,
       /**
        * 这一下点在尾巴上吗？
        *
-       * 和摸头同一套判定（模型自己的三角面），只是部件集合换成 cdi3 里命名为
-       * 尾/鳍/翅/翼 的那些。**没有尾巴部件时返回 false**（不是 true）：摸尾巴是个
-       * 新增的互动，测不出来就不该乱触发（摸头那边相反，它要兼容旧模型）。
+       * 和摸头同一套判定（模型自己的三角面），但部件集合不是"名字里带尾/翅的那些"，
+       * 而是**再收窄一次**：只留贴图落在尾鳍区域的那几块（见 `tailIndices()`）。
+       * 原因见那段注释 —— 16 块里 11 块是配件几何、横跨全身，全算上的话"处处是尾巴"，
+       * 而路由摸头优先，可见的尾鳍反而永远轮不到。
+       *
+       * **没有尾巴部件时返回 false**（不是 true）：摸尾巴是个新增互动，测不出来就不该
+       * 乱触发（摸头那边相反，它要兼容没有 cdi3 的旧模型）。
        */
       hitsTail(x, y) {
         if (model === null || vendor === null) return false;
         if (tailParts.length === 0) return false;
         try {
           const point = model.toModelPosition(new vendor.Point(x, y));
-          if (tailIndices === null) tailIndices = drawableIndicesForParts(tailParts);
-          const hit = hitsPartsGeometry(tailIndices, point.x, point.y);
+          const hit = hitsPartsGeometry(tailIndicesNow(), point.x, point.y);
           return hit === true;
         } catch {
           return false;
@@ -1956,6 +2584,35 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         const im = model?.internalModel;
         return typeof im?.getDrawableIDs === "function" ? Array.from(im.getDrawableIDs()).map(String) : [];
       },
+      /**
+       * 尾巴判定**实际用的**那几块 drawable（收窄的结果，见 `tailIndicesNow`）。
+       */
+      tailIndices: () => tailIndicesNow(),
+      /** Diagnostic: 尾巴判定的收窄结果（收窄前 / 收窄后各是哪些、各自贴在哪块贴图上）。 */
+      tailDebug: () => {
+        if (tailIndices === null) tailIndices = drawableIndicesForParts(tailParts);
+        const kept = tailIndicesNow();
+        const rows = (tailIndices ?? []).map((entry) => {
+          const uv = readUvs(entry.index);
+          return {
+            id: entry.id,
+            part: entry.part,
+            uv,
+            inFin: uvInsideTailFin(uv) === true,
+            kept: kept.some((row) => row.id === entry.id),
+          };
+        });
+        return {
+          parts: tailParts.length,
+          before: (tailIndices ?? []).length,
+          after: kept.length,
+          region: TAIL_FIN_UV,
+          // 实时盒子（hitsMask 会并进"算不算落在她身上"）与它的采样间隔。
+          liveBox: tailBoxLive,
+          sampleMs: TAIL_BOX_SAMPLE_MS,
+          rows,
+        };
+      },
       /**
        * Diagnostic: 引擎原始表里 drawable → 父部件 的对应关系。
        *
@@ -2422,6 +3079,7 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     ROOT_SEL + " [data-hit]{position:absolute;inset:0;cursor:grab;pointer-events:auto}",
     ROOT_SEL + " [data-stage][data-dragging] [data-hit]{cursor:grabbing}",
     ROOT_SEL + " [data-hit][data-off]{display:none}",
+    // 尾巴那一块（那一截矩形由 JS 每 ~120ms 跟着摆动重建，见 hitPath）。
     // Until the silhouette is known the whole box stays live, so the pet is
     // never inert; it degrades to the pre-mask behaviour instead of nothing.
     ROOT_SEL + " [data-stage][data-nomask]{pointer-events:auto;cursor:grab}",
@@ -2467,6 +3125,12 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     ROOT_SEL + " [data-panel] [data-tabs] button{flex:1;border:0;background:transparent;color:var(--pp-muted);font:600 11px/2 inherit;border-radius:7px;cursor:pointer}",
     ROOT_SEL + " [data-panel] [data-tabs] button[data-on]{background:var(--pp-accent);color:var(--pp-ink-strong)}",
     ROOT_SEL + " [data-panel] [data-body]{flex:1;overflow:auto;padding:8px}",
+    // 桌面端的「设置」页签把面板加宽一档：设置正文是**表格**（池子、相位、关系），
+    // 270px 里那几列会挤成一团。加宽只发生在这一个页签上，别的页签宽度不变。
+    ROOT_SEL + " [data-panel][data-wide]{width:342px}",
+    // 面板里的设置正文：字体与卡片内边距比设置页收一档，同样的内容不至于翻半天。
+    ROOT_SEL + " [data-panel-settings] [data-card-body]{padding:7px 9px}",
+    ROOT_SEL + " [data-panel-settings] [data-pool-row]{grid-template-columns:minmax(0,1fr) 64px 18px 52px;gap:3px}",
     ROOT_SEL + " [data-panel] [data-group]{margin-bottom:9px}",
     ROOT_SEL + " [data-panel] [data-group]>span{display:block;margin:0 0 4px 2px;color:var(--pp-dim);font-size:10px;letter-spacing:.06em}",
     ROOT_SEL + " [data-panel] [data-chips]{display:flex;flex-wrap:wrap;gap:4px}",
@@ -2506,6 +3170,17 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
    * 规则只写一遍、作用域各来一份，两个地方就不会再走岔。
    */
   const SETTINGS_SCOPES = [SETTINGS_SEL, ROOT_SEL + " [data-settings]"];
+
+  /**
+   * 是不是跑在桌面端（`dsh-live2d-pet-desktop` 的那个壳里）。
+   *
+   * 判据是页面运行时留下的标记，不是 UA、也不是壳直接告诉我们的：桌面端没有 DSH 的
+   * 客户端壳，所以 `ctx.slots` 那一节挂不上，设置正文得有**另一个**入口 —— 也就是
+   * 右键面板的第三个页签。**网页端不认这个标记，行为一个字都不变**（那里设置正文
+   * 的家仍然是 DSH 设置页）。
+   */
+  const desktopNow = () =>
+    typeof window !== "undefined" && window.__petDesktop !== undefined && window.__petDesktop !== null;
   /**
    * 视觉语言：**卡片**。每一组设置是一张卡片（标题条 + 内容区），池子、相位都住在
    * 卡片里，层级靠"卡片 > 行 > 药丸"三层表达，而不是一堆同权重的裸控件。
@@ -2760,8 +3435,39 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
    * 不需要再穿一层 setter。写进去下一帧就生效。
    */
   const TUNING = {
-    /** 指针离舞台多远仍能牵引视线，px。 */
-    gazeRange: 240,
+    /**
+     * **注视满偏半径**，px：离她中心多远算"看到最边上"（视线到这儿就满偏）。
+     *
+     * 它只是**满偏那一圈**，不是"还看不看她"（那是下面 `gazeWatchingRatio` 的倍数）。
+     * 两者合起来是一条连续的曲线（**正圆，只有一个半径**）：
+     *   * 距离比 0 → 1（= 这个半径）：视线按距离成比例偏转，到这儿满偏；
+     *   * 再往外到 `× gazeWatchingRatio`：强度缓动衰减到 0；
+     *   * 更远：当她没在看，视线回正。
+     * 早先只有"贴边"没有"衰减/回正"，于是 220px 之外一律"贴边斜眼" —— 鼠标跑到别的屏上
+     * 就变成"全屏都在追"（用户两次报的就是这个）。只贴边不回正，等于一直在盯着你。
+     *
+     * 上限是**视口的一半**：半径超过视野没有意义（远处一律贴边），而正圆不像椭圆那样能
+     * "竖直方向借一点"，所以可用半径就是这个框能容下的最大圆。
+     */
+    gazeRangePx: 220,
+    /**
+     * **视线能跟多远**（相对满偏半径的倍数）。
+     *
+     * 跟随强度由**到她的圆形距离比**决定，只有一处曲线，没有硬边界：
+     *
+     *   距离比 0 → 1（= `gazeRangePx`）        强度 0 → 1（成比例，到这儿满偏）
+     *   =1 … `gazeWatchingRatio`                强度 1 → 0（缓动衰减）
+     *   ≥ 倍数                                   强度 0：当她没在看，视线回正
+     *
+     * 为什么不要硬边界：早先写成"超过阈值立刻回正"，于是她要么满偏斜眼盯着、要么啪一下
+     * 回正，中间没有过渡 —— 用户看到的就是"全屏都在追踪"（贴边）或"突然不看了"。衰减
+     * 让远处"渐渐不感兴趣"，这也更像活物。
+     *
+     * 2.7 是按实际几何定的：她贴屏幕底边，桌面端视口高 1392 → 页面正中就离她 546px，
+     * 而满偏半径 220 × 2.7 ≈ 594 > 546，所以"在屏幕中部动鼠标"仍在范围内（只是强度很弱）。
+     * 小于 2.5 的话竖直方向会白白浪费掉半屏。
+     */
+    gazeWatchingRatio: 2.7,
     /** 中心附近被忽略的比例（死区）：没有它，手抖一像素眼珠就动。 */
     gazeDeadzone: 0.12,
     /** 嘴部：跟随强度 / 形状强度 / 缓动时间常数（ms）。 */
@@ -2794,7 +3500,10 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
    */
   const TUNING_FIELDS = [
     { key: "gazeDeadzone", label: "注视死区", min: 0, max: 0.6, step: 0.01 },
-    { key: "gazeRange", label: "注视范围 px", min: 0, max: 800, step: 10 },
+    // 「满偏半径」：离她多远算"看到最边上"。**调大 = 范围更大**（220 是"一个巴掌"）。
+    { key: "gazeRangePx", label: "注视满偏 px", min: 80, max: 900, step: 20 },
+    // 「收回倍数」：满偏的多大倍数之外当她没在看（中间那段是缓动衰减，不是硬边界）。
+    { key: "gazeWatchingRatio", label: "收回倍数", min: 1.2, max: 6, step: 0.1 },
     { key: "mouthFollow", label: "嘴跟随意", min: 0, max: 1, step: 0.05 },
     { key: "mouthDrop", label: "嘴形强度", min: -1, max: 1, step: 0.05 },
     { key: "mouthEaseMs", label: "嘴缓动 ms", min: 30, max: 800, step: 10 },
@@ -2824,6 +3533,146 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
   /** 装扮存档的 key。放这里是因为开关（applyFlag）也要用它清存档。 */
   const OUTFIT_KEY = "dsh-pet-live2d:outfit";
 
+  // ---------------------------------------------------------------------------
+  // 共享设置：**宿主优先，localStorage 兜底**
+  //
+  // 用户报的"桌面的设置与 DSH 里的设置没有同步"。根因不是"同步没写"，而是**两边根本
+  // 不共享存储**：桌面端页面是 `http://127.0.0.1:<壳的随机端口>`，DSH 是
+  // `http://127.0.0.1:3080` —— localStorage 按 origin 隔离，各存一份、永不互见。
+  //
+  // 所以三类**跨窗口该一致**的设置（可调项 / 相位池子覆盖+开关 / 装扮）走宿主：
+  // 插件宿主半区把它们落在 `%DSH_HOME%\pet-settings.json`，两个页面都读它。
+  // 窗口自己的东西（位置、大小）仍然留在 localStorage —— 那本来就该各窗口不同。
+  //
+  // 独立模式（DSH 不在）时 `/api/live2d-pet/settings` 是 404，于是自然退回 localStorage，
+  // 行为与以前一致。
+  // ---------------------------------------------------------------------------
+  const SETTINGS_URL = "/api/live2d-pet/settings";
+  /** 轮询间隔：跨窗口同步靠它（localStorage 的 `storage` 事件不跨 origin）。 */
+  const SHARED_POLL_MS = 3000;
+  /** 轮询定时器（模块级一份 —— 热重载/重复 apply 不该堆出好几个）。 */
+  let sharedPoll = 0;
+  /**
+   * 把"宿主拉回来的装扮"应用到画面上的回调。
+   *
+   * **必须是模块级的桥**：槽位选择与 pin 都在 `Pet` 组件里（`slotSelectionsRef` /
+   * `commitPinsRef`），而拉取/轮询是模块级的 `apply()` 起的 —— 直接引用会 ReferenceError，
+   * 而且是**静默**的那种（client-state skill 里那几次都是这个）。所以由 `Pet` 挂上来。
+   */
+  const applyOutfitRef = { current: null };
+  /**
+   * 宿主存档里的键 → localStorage 键。
+   *
+   * ⚠️ **必须惰性构造**：`OVERRIDE_KEY` 在下面（和 `saveOverrides` 挨着）才声明，
+   * 在模块加载期直接写一个对象字面量会撞 TDZ —— 症状是**整个插件 import 失败**：
+   *   `dsh-pet-live2d: import failed: Cannot access 'OVERRIDE_KEY' before initialization`
+   * （我第一版就是这么写的，直接把页面打成 "Failed to load plugins"。）
+   */
+  const sharedKeys = () => ({ tuning: TUNING_KEY, overrides: OVERRIDE_KEY, outfit: OUTFIT_KEY });
+  /** 宿主那份的版本号；每次 POST 回来或轮询发现变化时更新。 */
+  let sharedRev = -1;
+  /** 宿主可用吗（第一次探测的结果；404 就不再问了，省得每 3 秒白跑一次）。 */
+  let hostAvailable = null;
+  /** 正在把宿主的改动往内存里灌 —— 期间不要回写宿主，否则自己写自己读打转。 */
+  let applyingHost = false;
+
+  const readLocal = (key) => {
+    try {
+      const raw = window.localStorage.getItem(key);
+      return raw === null ? null : JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  };
+  const writeLocal = (key, value) => {
+    try {
+      if (value === null || value === undefined) window.localStorage.removeItem(key);
+      else window.localStorage.setItem(key, JSON.stringify(value));
+    } catch {
+      /* 无痕模式之类：这次生效，下次不记得 */
+    }
+  };
+
+  /** 把一份宿主存档按 key 写进 localStorage 并调用方负责灌内存。 */
+  const cacheHost = (payload) => {
+    for (const [name, key] of Object.entries(sharedKeys())) {
+      const value = payload?.[name];
+      if (value === undefined) continue;
+      writeLocal(key, value === null ? null : value);
+    }
+  };
+
+  /**
+   * 三个界面（DSH 设置页 / 桌面右键面板 / 独立模式的桌面壳）共用同一份值的落点。
+   *
+   * 有宿主就写宿主（两端都能看见），同时留一份 localStorage 当"宿主不在时的兜底"。
+   */
+  const persistShared = (patch) => {
+    for (const [name, key] of Object.entries(sharedKeys())) {
+      if (patch[name] === undefined) continue;
+      writeLocal(key, patch[name]);
+    }
+    if (applyingHost) return;
+    if (hostAvailable === false) return;
+    try {
+      void fetch(SETTINGS_URL, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(patch),
+        cache: "no-store",
+      }).then((response) => {
+        if (response.status === 404) { hostAvailable = false; return null; }
+        if (!response.ok) return null;
+        return response.json();
+      }).then((payload) => {
+        if (payload === null || payload === undefined) return;
+        hostAvailable = true;
+        if (typeof payload.rev === "number") sharedRev = payload.rev;
+      }).catch(() => { /* 宿主不在就算了，本地那份已经写好了 */ });
+    } catch {
+      /* 同上 */
+    }
+  };
+
+  /**
+   * 拉一次宿主存档；有变化就灌进内存并广播。
+   *
+   * 这是"另一个窗口改了、这个窗口跟着变"的唯一途径 —— localStorage 的 `storage` 事件
+   * **不会跨 origin 触发**，所以必须轮询（3 秒一次，代价可以忽略）。
+   */
+  const pullShared = async (apply) => {
+    if (hostAvailable === false) return false;
+    let payload = null;
+    try {
+      const response = await fetch(SETTINGS_URL, { cache: "no-store" });
+      if (response.status === 404) { hostAvailable = false; return false; }
+      if (!response.ok) return false;
+      payload = await response.json();
+    } catch {
+      return false;
+    }
+    if (payload === null || typeof payload !== "object") return false;
+    hostAvailable = true;
+    const rev = typeof payload.rev === "number" ? payload.rev : 0;
+    if (rev === sharedRev) return false;
+    sharedRev = rev;
+    cacheHost(payload);
+    applyingHost = true;
+    try {
+      apply(payload);
+    } finally {
+      applyingHost = false;
+    }
+    return true;
+  };
+
+  /** 把一份共享存档灌进内存（tuning / overrides / outfit 各自的应用由调用方给）。 */
+  const applyShared = (payload, hooks) => {
+    if (payload?.tuning !== null && payload?.tuning !== undefined) hooks.tuning(payload.tuning);
+    if (payload?.overrides !== null && payload?.overrides !== undefined) hooks.overrides(payload.overrides);
+    if (payload?.outfit !== null && payload?.outfit !== undefined) hooks.outfit(payload.outfit);
+  };
+
   /** 把存档里的值夹进合法区间 —— 坏值不能让宠物动不了。 */
   const clampSetting = (field, value) => Math.min(field.max, Math.max(field.min, value));
 
@@ -2994,11 +3843,8 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
   const OVERRIDE_KEY = "dsh-pet-live2d.settings.v2";
 
   const saveOverrides = () => {
-    try {
-      window.localStorage.setItem(OVERRIDE_KEY, JSON.stringify(Object.assign({}, PHASE_OVERRIDES, { flags: FLAGS })));
-    } catch {
-      /* 无痕模式之类：这次生效，下次不记得 */
-    }
+    // 走共享落点（宿主优先）：相位池子覆盖与开关两个窗口共用同一份。
+    persistShared({ overrides: Object.assign({}, PHASE_OVERRIDES, { flags: FLAGS }) });
   };
 
   /** 开关类设置：存档 + 广播（装扮存档开关关掉时顺带清掉那份存档）。 */
@@ -3037,12 +3883,20 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
   };
 
   /** 读回存档；值只做类型校验，范围由调用方按权重语义处理。 */
-  const restoreOverrides = () => {
-    let saved = null;
-    try {
-      saved = JSON.parse(window.localStorage.getItem(OVERRIDE_KEY) ?? "null");
-    } catch {
-      saved = null;
+  /**
+   * 读回相位池子覆盖 + 开关。
+   *
+   * `given` 传进来时用它（宿主拉回来的那份），否则读 localStorage —— 两条路的清洗逻辑
+   * 是同一份，别写第二遍（写第二遍的下场是两边清洗规则慢慢分叉）。
+   */
+  const restoreOverrides = (given) => {
+    let saved = given === undefined ? null : given;
+    if (saved === undefined || saved === null) {
+      try {
+        saved = JSON.parse(window.localStorage.getItem(OVERRIDE_KEY) ?? "null");
+      } catch {
+        saved = null;
+      }
     }
     if (saved === null || typeof saved !== "object") return;
     const phases = saved.phases;
@@ -3377,11 +4231,8 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       const field = TUNING_FIELDS.find((entry) => entry.key === key);
       TUNING[key] = field === undefined ? value : clampSetting(field, value);
     }
-    try {
-      window.localStorage.setItem(TUNING_KEY, JSON.stringify(TUNING));
-    } catch {
-      /* 无痕模式之类：这次改动仍然生效，只是下次不记得 */
-    }
+    // 走共享落点：有宿主就写宿主（DSH 与桌面端两个窗口都能看见），本地留一份兜底。
+    persistShared({ tuning: Object.assign({}, TUNING) });
     notifySettings();
   };
 
@@ -3390,12 +4241,14 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
    *
    * 手改坏了存档最多回到合法范围，不会出现「死区 5」这种把宠物冻住的配置。
    */
-  const restoreTuning = () => {
-    let saved = null;
-    try {
-      saved = JSON.parse(window.localStorage.getItem(TUNING_KEY) ?? "null");
-    } catch {
-      saved = null;
+  const restoreTuning = (given) => {
+    let saved = given === undefined ? null : given;
+    if (saved === undefined || saved === null) {
+      try {
+        saved = JSON.parse(window.localStorage.getItem(TUNING_KEY) ?? "null");
+      } catch {
+        saved = null;
+      }
     }
     if (saved === null || typeof saved !== "object") return;
     let restored = false;
@@ -3600,6 +4453,30 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     spinReactions: ["晕晕"],
   };
 
+  /**
+   * 某些反应开演前要**先清掉**的槽位（标签 → 槽位 id → 该让位的选项名单；空数组 = 全清）。
+   *
+   * 用户报的：「重锤出击动作应该判断一下当前眼部是不是 晕晕/呆呆眼，情绪是不是
+   * 开心兴奋/闭眼口水，如果是应该先把眼部或情绪还原为默认」。
+   *
+   * 理由：`Hammer` 只写手臂参数，脸它一概不管。于是眼部停在「晕晕」、情绪停在「闭眼口水」
+   * 时挥锤，画面上是"一个晕乎乎、闭着眼流口水的人在奋力挥锤"——动作与表情自相矛盾。
+   * 只清**列出来的**那几个选项：用户选的其它眼睛（星星眼之类）不该被这一锤抹掉。
+   *
+   * 用户可配（设置里那份覆盖）：`PHASE_OVERRIDES.interactions.clearSlots`。
+   */
+  const DEFAULT_REACTION_CLEARS = {
+    重锤出击: { eyes: ["晕晕", "呆呆眼"], mood: ["开心兴奋", "闭眼口水"] },
+  };
+
+  /**
+   * 反应留下的槽位改动**多久之后收回默认**（用户要求"过一段事件（时间）应该还原为默认"）。
+   *
+   * 12 秒与手动点的表情同一个上限（`EXPRESSION_HOLD_MS`）—— 都属"临时效果"，
+   * 两套时长不一致会让用户觉得其中一个是坏的。
+   */
+  const REACTION_REVERT_MS = 12000;
+
   /** 一组反应候选的来历（诊断用，见 reactionSource）。 */
   const REACTION_KEYS = Object.keys(DEFAULT_REACTIONS);
 
@@ -3803,6 +4680,41 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
   /** Alpha above which a sampled pixel counts as part of the character. */
   const HIT_MASK_ALPHA = 24;
 
+  /**
+   * 贴图上**真正属于尾巴**的那一块（归一化 UV）。
+   *
+   * 为什么这是一个常量而不是"名字里带尾/翅的部件"：这只宠物有 **16 块** drawable 命中
+   * `尾|鳍|翅|翼`，但其中 **11 块是可换配件**（狐狸尾 / 猫尾 / 狼尾 / 天使翅膀 /
+   * 恶魔翅膀…），几何**一直留在原地**、横跨从头顶到腰腹的整个角色。把它们全算成尾巴，
+   * 结果是"算尾巴"的格子占角色 **22%**，其中 **86.6% 同时算头** —— 而路由是摸头优先，
+   * 于是用户点在**可见的尾鳍**上拿到的是摸头反应（用户报的"摸尾巴很难点到"）。
+   *
+   * 依据是**贴图**（作者自己画的）：`texture_00.png` 2048² 上，鲸鱼尾鳍只占
+   * `x 3..444, y 953..1397` 这一块，对应下面这个归一化区域。实测落在这里的正好是
+   * `ArtMesh38 / 56 / 58 / 59 / 60` 五块，全部属于部件 `尾巴(蒙皮)`；其余 11 块各自
+   * 落在贴图别处（`ArtMesh75` 落在 600,1592 → 1069,2045 那片大翅膀上）。
+   *
+   * UV 读不到时（别的引擎版本、没有 `vertexUvs` 表）**不做任何收窄** —— 退回旧行为，
+   * 不能让"判定变得精确"变成"判定整个失效"。
+   */
+  const TAIL_FIN_UV = { minU: 0, minV: 0.45, maxU: 0.23, maxV: 0.72 };
+
+  /** 一块 drawable 的 UV 包围盒整体落在这个区域里吗（留一点边距）。 */
+  function uvInsideTailFin(uv) {
+    if (uv === null) return null;
+    const pad = 0.02;
+    return uv.minU >= TAIL_FIN_UV.minU - pad && uv.maxU <= TAIL_FIN_UV.maxU + pad
+      && uv.minV >= TAIL_FIN_UV.minV - pad && uv.maxV <= TAIL_FIN_UV.maxV + pad;
+  }
+
+  /**
+   * 尾鳍实时包围盒的采样间隔（ms）。
+   *
+   * 100ms ≈ 6 帧一次：摆动一个来回大约 30 帧，所以盒子永远落后不超过摆动幅度的几分之一，
+   * 而每帧读几十个顶点是白烧 CPU。采样点在 `saveParameters` 缝里（这一帧真正要画的姿势）。
+   */
+  const TAIL_BOX_SAMPLE_MS = 100;
+
   /**
    * Build a coarse opacity grid of the character as actually rendered.
    *
@@ -4049,6 +4961,14 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         windowMs: TUNING.spinWindowMs,
         threshold: TUNING.spinTurns * Math.PI * 2,
       });
+      /**
+       * 诊断：**上一下按住的三个答案**（onModel / onHead / onTail，以及事件被哪一层接住）。
+       *
+       * "点了没反应"要先分清卡在哪一段：事件没进宠物（截不住 / 穿透到页面）、
+       * 路由判成"身体"（只有台词）、还是判定本身说不在她身上。从"她说了什么"倒推
+       * 这三件事是分不出来的 —— 尾巴那一串问题就是这么绕了好几轮的。
+       */
+      api.lastPress = () => lastPressRef.current;
     }, []);
     /**
      * The pins the USER owns (slot choices, flashes) and the pins the SESSION
@@ -4162,6 +5082,15 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       return () => window.cancelAnimationFrame(id);
     }, [panelOpen]);
     const [tab, setTab] = useState("motions");
+    /**
+     * 显示层状态：**订阅模块级的 store**（不是本地 ref）。
+     *
+     * 轮询由模块级单例负责（`ensureLayerPolling`）—— 它**必须**不依赖这个组件：
+     * 用户在设置里选了"桌面"之后，页面里这只就让位了，而这个组件一旦不渲染，
+     * 由它驱动的轮询也就停了，设置页那一行便永远停在旧文本上（实测：要重开设置页才更新）。
+     */
+    const layer = useLayerState();
+    useEffect(() => { ensureLayerPolling(); }, []);
     // 设置值在模块作用域的 store 里（DSH 设置页和这里的面板共用一份）。
     // 订阅它既为重渲染，也为下面那个「相位映射随设置重算」的 effect 提供依赖。
     const settingsRev = useSettings();
@@ -4523,6 +5452,64 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       return () => observer.disconnect();
     }, []);
 
+    /**
+     * 尾巴那一层可点区域的**动态更新**。
+     *
+     * 尾鳍一直摆，而 `[data-hit]` 的轮廓是开机快照 —— 摆出去就点不到（事件穿透到页面）。
+     * 这里按固定间隔把尾巴此刻的包围盒（模型空间）换算成舞台上的百分比矩形：
+     *
+     *   模型空间 → 舞台：`model.getBounds()` 给的是舞台局部盒，
+     *   尾巴各 drawable 的并集盒 → 按比例映射进那个盒子里（同一套映射，
+     *   不猜 anchor / scale，换缩放、换宠物都成立）。
+     *
+     * 间隔 120ms 是刻意的：尾鳍一个摆动来回约 0.5 秒，取 1/4 个周期足够跟上，
+     * 而每帧 setState 会让整个宠物重渲染 —— 那是白烧。**只在格子真的变了才 setState**，
+     * 静止时一个渲染都不产生。
+     */
+    useEffect(() => {
+      if (!ready) return undefined;
+      let last = "";
+      const tick = () => {
+        const api = motion.current;
+        const stage = stageRef.current;
+        if (api === null || stage === null) return;
+        // 诊断开关：`window.__petNoTailLayer = true` 之后这一层不再拼进 `clip-path`。
+        // 用它一次就能量出"尾巴层到底贡献了多大一片可摸区"（对比量比反复改代码猜快得多）。
+        const hull = window.__petNoTailLayer === true
+          ? null
+          : (typeof api.tailRectNow === "function" ? api.tailRectNow() : null);
+        if (hull === null || typeof api.modelToStage !== "function") {
+          if (last !== "") { last = ""; setTailPath(""); }
+          return;
+        }
+        const rect = stage.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) return;
+        // **逐块一个矩形**，拼成一条 path（`clip-path` 默认 nonzero，重叠部分照样算内部）。
+        //
+        // 这里不再做空间映射：`tailRectNow()` 已经给的是**舞台局部像素**（它内部把四个角
+        // 都映射过了）。第一版在这里先并成一个大盒再映射，结果框进 43%×54% 的空白 ——
+        // 用户看到的就是"右下角明明什么都没有却能摸"。
+        let next = "";
+        for (const box of hull) {
+          const left = Math.max(0, Math.min(rect.width, box.x0));
+          const top = Math.max(0, Math.min(rect.height, box.y0));
+          const right = Math.max(0, Math.min(rect.width, box.x1));
+          const bottom = Math.max(0, Math.min(rect.height, box.y1));
+          const width = right - left;
+          const height = bottom - top;
+          if (!(width > 0) || !(height > 0)) continue;
+          next += "M" + left.toFixed(1) + " " + top.toFixed(1)
+            + "h" + width.toFixed(1) + "v" + height.toFixed(1) + "h-" + width.toFixed(1) + "Z";
+        }
+        if (next === last) return;
+        last = next;
+        setTailPath(next);
+      };
+      tick();
+      const timer = window.setInterval(tick, 120);
+      return () => window.clearInterval(timer);
+    }, [ready]);
+
     // ---- greeting -----------------------------------------------------
     useEffect(() => {
       if (!ready || greeted.current) return;
@@ -4541,10 +5528,10 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       if (stage === null) return undefined;
       // The resting target is the stage centre, i.e. where the model sits.
       focusDefaultRef.current = () => {
-        const rect = stage.getBoundingClientRect();
         // The DEFAULT resting target is the model's own centre — not the last
         // pointer position — so the pet always settles back to a neutral gaze.
-        motion.current.updatePointer(rect.width / 2, rect.height / 2, rect.width, rect.height);
+        // 偏移 0 = 正中，与"满偏半径"无关（视线回中不该受那个参数影响）。
+        motion.current.updatePointer(0, 0, 320);
         reportGaze("center");
       };
       let resting = false;
@@ -4596,36 +5583,114 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         if (list.length > 0) runReactionRef.current(pick(list));
         say(pick(linesNow().spin));
       };
-      const onMove = (event) => {
+      /**
+       * 跟随一次指针位置（**视口坐标**）。
+       *
+       * 两个来源，同一条逻辑：
+       *   * 网页端 / 指针在窗口内时 —— DOM 的 `pointermove`（浏览器只在落点位于本窗口时送来）；
+       *   * **桌面端 + 指针在别的程序上** —— 由壳喂进来（`window.__petPointer`）。
+       *     没有这条通道时，用户一离开宠物窗口她就不跟了（这正是"只有焦点在宠物上才有跟随"）。
+       *
+       * **坐标系是视口，不是她那个盒子。** 原来把坐标减去 `stage.getBoundingClientRect()`，
+       * 于是盒子外的点全被当成"远得没边"（判据半径又只有 240px），整段跟随就断了。
+       * 现在：以她的**中心**为原点、按像素距离归一化，`gazeRangePx` 是满偏半径。
+       */
+      const onMove = (clientX, clientY, source) => {
         const rect = stage.getBoundingClientRect();
-        const x = event.clientX - rect.left;
-        const y = event.clientY - rect.top;
+        // 她在视口里的中心（`rect` 只用来定位她，不再用来归一化）。
+        const centreX = rect.left + rect.width / 2;
+        const centreY = rect.top + rect.height / 2;
+        const dx = clientX - centreX;
+        const dy = clientY - centreY;
+        // 满偏半径：**按像素算，不按盒子算**。
+        //
+        // 旧契约是"偏移 ÷ 她盒子的一半"，缺点在桌面端很明显：盒子是 300px，于是**全屏**
+        // 的移动都落在"盒子外的死区"里，一离开她那个方块就不跟了（用户报的"跟随范围有问题"）。
+        // 像素契约修好了那一段，但**范围要给对**：见 `gazeRangePx` 的注释 —— 它是"从多远
+        // 开始贴边"，调大了就成了"全屏都在跟且处处满偏"。
+        // 满偏半径：**正圆，一个半径说了算**。
+        //
+        // 旧契约是"偏移 ÷ 她盒子的一半"，缺点在桌面端很明显：盒子是 300px，于是**全屏**
+        // 的移动都落在"盒子外的死区"里，一离开她那个方块就不跟了（用户报的"跟随范围有问题"）。
+        //
+        // 上限取**视口半高/半宽**：半径超过视野就没有意义（远处一律贴边），而正圆又不能像
+        // 椭圆那样"竖直方向借一点" —— 所以允许的半径就是这个框能容下的最大圆。
+        const range = Math.max(
+          Math.min(rect.width, rect.height) / 2,
+          Math.min(TUNING.gazeRangePx, Math.min(window.innerWidth, window.innerHeight) / 2),
+        );
+        // ---- 太远就当她没在看（衰减，不是硬边界）-----------------------------
+        //
+        // 判据是**到她的圆形距离** `u = hypot(dx, dy) / range`：
+        //   * `u ≤ 1`：在满偏圆内，强度 1；
+        //   * `1 < u < ratio`：强度从 1 缓动衰减到 0 —— 她"渐渐不感兴趣"；
+        //   * `u ≥ ratio`：当她没在看，视线回正。
+        //
+        // 为什么不要硬边界：早先写成"超过阈值立刻回正"，于是她要么满偏斜眼盯着、要么啪一下
+        // 回正，中间没有过渡 —— 用户看到的就是"全屏都在追踪"（贴边）或"突然不看了"。
+        // 衰减让远处"渐渐不感兴趣"，这也更像活物。
+        const watching = range * TUNING.gazeWatchingRatio;
+        const u = Math.hypot(dx, dy) / range;
+        const strength = u <= 1 ? 1 : (u >= TUNING.gazeWatchingRatio ? 0 : (TUNING.gazeWatchingRatio - u) / (TUNING.gazeWatchingRatio - 1));
+        if (strength <= 0) {
+          // 她没在看：回中位，并把对外状态标回 `center`（驱动与用户都看得见这一点）。
+          if (!resting) {
+            resting = true;
+            focusDefault();
+          }
+          gazeTrace.current = {
+            dx: Math.round(dx), dy: Math.round(dy),
+            at: { x: Math.round(clientX), y: Math.round(clientY) },
+            centre: { x: Math.round(centreX), y: Math.round(centreY) },
+            box: { w: Math.round(rect.width), h: Math.round(rect.height) },
+            range: Math.round(range),
+            watching: Math.round(watching),
+            distanceRatio: Number(u.toFixed(3)), strength: 0,
+            tuningPx: TUNING.gazeRangePx,
+            source: source ?? "dom", skipped: "out-of-watching-range",
+          };
+          return;
+        }
         // ---- 鼠标围着转圈 → 转晕 ------------------------------------------
         // 判定的是"围绕舞台中心的**累计转角**"：每次移动取与上一次的夹角增量
         // （归一化到 ±180°），在一段时间窗内累计；够 spinTurns 圈就触发一次。
         // 用累计角而不是"位置绕了几圈"，是因为前者对半径不敏感 —— 贴着角色转
         // 小圈和远远地转大圈都算，符合"逗她"的直觉。
-        spinTrack(rect, x, y);
-        const near = x >= -TUNING.gazeRange && y >= -TUNING.gazeRange
-          && x <= rect.width + TUNING.gazeRange && y <= rect.height + TUNING.gazeRange;
-        if (near) {
-          resting = false;
-          motion.current.updatePointer(x, y, rect.width, rect.height);
-          reportGaze("pointer");
-        } else if (!resting) {
-          resting = true;
-          focusDefault();
-        }
+        // ⚠️ `spinTrack` 要的是**盒子内的坐标**（它围绕舞台中心算累计转角），这里给的是
+        // 视口坐标 —— 必须转回去。直接传视口坐标的后果是"围绕一个远处的点转小角"，
+        // 累计转角小到永远够不着阈值（实测 103 次移动只累计 0.13 弧度，阈值 12.57）。
+        spinTrack(rect, clientX - rect.left, clientY - rect.top);
+        // 诊断读口：跟随范围这一块最容易"看着像没反应"，把中间量挂出来，
+        // 驱动量到异常时一眼能看出是判据错了还是参数没生效（只读，不影响行为）。
+        gazeTrace.current = {
+          dx: Math.round(dx), dy: Math.round(dy),
+          at: { x: Math.round(clientX), y: Math.round(clientY) },
+          centre: { x: Math.round(centreX), y: Math.round(centreY) },
+          box: { w: Math.round(rect.width), h: Math.round(rect.height) },
+          range: Math.round(range),
+          watching: Math.round(watching),
+          distanceRatio: Number(u.toFixed(3)), strength: Number(strength.toFixed(3)),
+          tuningPx: TUNING.gazeRangePx,
+          source: source ?? "dom",
+        };
+        resting = false;
+        // 强度乘在偏移上：满偏圆内是 1（与原行为一致），远处按**圆形距离比**平滑衰减到 0。
+        motion.current.updatePointer(dx * strength, dy * strength, range);
+        reportGaze("pointer");
       };
       /**
        * 指针「不在场」了：回正。
        *
-       * 鼠标一旦移出窗口，pointermove 就不再发来，宠物会**僵在最后一个注视方向**上
-       * （用户报的就是这个）。页面拿不到窗口外的指针位置——那需要原生钩子，浏览器
-       * 里没有这个能力——所以这里能做的是回正：离开窗口 / 窗口失焦 / 切标签页，
-       * 都当成指针不在场，视线与嘴一起缓动回中位。
+       * 网页端：鼠标移出窗口后 `pointermove` 不再发来，宠物会僵在最后一个注视方向上，
+       * 所以离开窗口 / 失焦 / 切标签页都当成"指针不在场"，视线与嘴缓动回中位。
+       *
+       * **桌面端不要走这条**：那边由壳持续喂全局光标位置（`window.__petPointer`），指针
+       * "离开窗口"根本不代表它不存在 —— 恰恰相反，用户在别的程序里动鼠标时她**应该**跟着。
+       * 所以桌面端把 `mouseleave`/`blur` 的回正效果压掉，只在壳明确说"指针不在场"时回正
+       * （壳那边有 `outside` 判定）。
        */
       const onLeave = () => {
+        if (isDesktopShell) return;
         if (resting) return;
         resting = true;
         focusDefault();
@@ -4634,12 +5699,22 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       root.addEventListener("mouseleave", onLeave);
       window.addEventListener("blur", onLeave);
       document.addEventListener("visibilitychange", onLeave);
-      window.addEventListener("pointermove", onMove, { passive: true });
-      return () => {
-        window.removeEventListener("pointermove", onMove);
+      // DOM 路径：指针落在本窗口内时走它（网页端全部走它；桌面端在窗口内也走它）。
+      const onDomMove = (event) => onMove(event.clientX, event.clientY, "dom");
+      window.addEventListener("pointermove", onDomMove, { passive: true });
+      // 壳路径：**桌面端专有** —— 指针在别的程序上时 DOM 一个事件都不会有，只有壳知道它在哪。
+      if (isDesktopShell) {
+        externalPointer.handler = (x, y) => {
+          onMove(x, y, "shell");
+          // 壳喂进来的位置说明指针在场（它是在读全局光标），把"回正"的状态解除掉。
+          resting = false;
+        };
+      }      return () => {
+        window.removeEventListener("pointermove", onDomMove);
         root.removeEventListener("mouseleave", onLeave);
         window.removeEventListener("blur", onLeave);
         document.removeEventListener("visibilitychange", onLeave);
+        if (isDesktopShell) externalPointer.handler = null;
         focusDefaultRef.current = () => {};
       };
     }, [ready]);
@@ -4840,16 +5915,13 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     const saveOutfit = () => {
       // 开关关掉就既不存也不读（见设置页「装扮」那一节）。
       if (!FLAGS.outfitArchive) return;
-      try {
-        const out = {};
-        for (const id of OUTFIT_SLOTS) {
-          const label = slotSelectionsRef.current[id];
-          if (label !== undefined) out[id] = label;
-        }
-        window.localStorage.setItem(OUTFIT_KEY, JSON.stringify(out));
-      } catch {
-        /* 无痕模式之类存不下：不影响这次，只是下次不记得 */
+      const out = {};
+      for (const id of OUTFIT_SLOTS) {
+        const label = slotSelectionsRef.current[id];
+        if (label !== undefined) out[id] = label;
       }
+      // 走共享落点：宿主在就写宿主（另一个窗口也能看见），顺带留一份本地兜底。
+      persistShared({ outfit: out });
     };
     const readOutfit = () => {
       if (!FLAGS.outfitArchive) return null;
@@ -4916,27 +5988,160 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     }, [armExpressionClear]);
 
     /**
-     * 跑一条互动反应（点击 / 转圈触发）。
+     * 跑一条互动反应（摸头 / 摸尾巴 / 转圈转晕）。
+     *
+     * **反应不该还原当前动作**：开演之前先记下她在演什么（`resumeAfter`），演完由
+     * `finishAction` 接回去 —— 于是摸一下头，举着的手还举着、泡泡还在。
      *
-     * 标签先当**动作组**找（宠物在 catalog.json 里给动作起了中文名），找不到就当
-     * **表达式**闪一下（闪完由 EXPRESSION_HOLD_MS 自动收，不会永久占着槽位）。
+     * 反应本身优先走"**随机换一个槽位里的选项**"（`chooseSlotOption` 那条路）：抽中的标签
+     * 是某个装扮槽位的选项时，换的就是**那一格**，别的槽位与当前动作都不受影响 ——
+     * 这正是用户要的"随机到哪一个插槽里的就放哪一个插槽里的"。
+     *
+     * 兜底两级，都不能变成"这个互动没反应"：
+     *   ① 是某个槽位的选项 → 换那一格；
+     *   ② 不是选项 → 当**动作组**播一次（播完接回原动作）；
+     *   ③ 再不是 → 当**表达式**闪一下（闪完自动收，不占槽位）。
+     */
+    /**
+     * 这次反应改过哪些槽位（收回默认时只动它们）。
+     *
+     * **必须是 ref**：`runReaction` 是 `useCallback`、计时器回调又是另一个闭包，普通 `const`
+     * 每次 render 都重建、两边各持一份 —— 收回时读到的永远是空的（client-state skill 里
+     * 那三次"功能正常但读数是 0"就是这个毛病）。
+     */
+    const reactionTouchedRef = useRef(new Set());
+    /** 收回默认的计时器（同样必须是 ref：跨 render 存活）。0 = 没在计时。 */
+    const reactionRevertRef = useRef(0);
+
+    function noteReactionTouched(slotId) {
+      reactionTouchedRef.current.add(slotId);
+    }
+
+    /**
+     * 反应留下的槽位改动**过一会儿收回默认**（②④：摸头 / 摸尾巴 / 转晕都算）。
+     *
+     * 收回的是"这次反应碰过的槽位"，用 `chooseSlotOption(slot, null)` 回**默认**选项
+     * （不是回上一个选择 —— 用户要的是"还原为默认"）。
+     * 重复触发时重新计时：摸三下头，最后一下之后才开始数。
+     */
+    function armReactionRevert() {
+      window.clearTimeout(reactionRevertRef.current);
+      reactionRevertRef.current = window.setTimeout(() => {
+        reactionRevertRef.current = 0;
+        const touched = Array.from(reactionTouchedRef.current);
+        reactionTouchedRef.current = new Set();
+        for (const slotId of touched) {
+          const slot = (petRef.current?.expressionSlots ?? []).find((candidate) => candidate.id === slotId);
+          if (slot === undefined) continue;
+          if (slotSelectionsRef.current[slotId] === undefined) continue;
+          chooseSlotOption(slot, null, false);
+        }
+      }, REACTION_REVERT_MS);
+    }
+
+    /**
+     * 这条反应开演前要先清掉哪些槽位（标签 → 槽位 id → 该让位的选项名单；空数组 = 全清）。
+     *
+     * 用户可配：`PHASE_OVERRIDES.interactions.clearSlots`。默认那一条见
+     * `DEFAULT_REACTION_CLEARS`（重锤出击 vs 晕晕/呆呆眼 + 开心兴奋/闭眼口水）。
+     */
+    function reactionClears(label) {
+      const user = PHASE_OVERRIDES.interactions?.clearSlots?.[label];
+      if (user !== undefined && user !== null && typeof user === "object") return user;
+      const declared = MANIFEST.current?.reactionClears?.[label];
+      if (declared !== undefined && declared !== null && typeof declared === "object") return declared;
+      return DEFAULT_REACTION_CLEARS[label] ?? {};
+    }
+
+    /**
+     * 跑一条互动反应（摸头 / 摸尾巴 / 转圈转晕）。
+     *
+     * **反应不该还原当前动作**：开演之前先记下她在演什么（`resumeAfter`），演完由
+     * `finishAction` 接回去 —— 于是摸一下头，举着的手还举着、泡泡还在。
+     *
+     * 反应本身优先走"**随机换一个槽位里的选项**"（`chooseSlotOption` 那条路）：抽中的标签
+     * 是某个装扮槽位的选项时，换的就是**那一格**，别的槽位与当前动作都不受影响 ——
+     * 这正是用户要的"随机到哪一个插槽里的就放哪一个插槽里的"。
+     *
+     * 兜底两级，都不能变成"这个互动没反应"：
+     *   ① 是某个槽位的选项 → 换那一格；
+     *   ② 不是选项 → 当**动作组**播一次（播完接回原动作）；
+     *   ③ 再不是 → 当**表达式**闪一下（闪完自动收，不占槽位）。
      */
     const runReaction = useCallback((label) => {
       if (typeof label !== "string" || label === "") return false;
+      // ①' 声明式的"先清掉"：动作只写手臂参数时，留着眼部/情绪会画出"晕乎乎的人在挥锤"。
+      const clears = reactionClears(label);
+      for (const slotId of Object.keys(clears)) {
+        const slot = (petRef.current?.expressionSlots ?? []).find((candidate) => candidate.id === slotId);
+        if (slot === undefined) continue;
+        const current = slotSelectionsRef.current[slotId];
+        if (current === undefined) continue;
+        const labels = clears[slotId];
+        // 空数组 = 清掉这一格；非空 = 只清列出来的那几个选项（当前选择不在名单里就不动）。
+        if (Array.isArray(labels) && labels.length > 0 && !labels.includes(current)) continue;
+        chooseSlotOption(slot, null, false);
+        noteReactionTouched(slotId);
+      }
+      // ① 抽中的标签落在某个装扮槽位里：换掉那一格。
+      for (const slot of petRef.current?.expressionSlots ?? []) {
+        const option = (slot.options ?? []).find((candidate) => candidate.label === label);
+        if (option !== undefined) {
+          // `satisfy = true`：手动互动等同于用户自己点它（前提由插件补齐，比如点自拍会
+          // 先把手机掏出来）。自动路径（摸鱼/相位）才不能补。
+          chooseSlotOption(slot, option, true);
+          noteReactionTouched(slot.id);
+          armReactionRevert();
+          return true;
+        }
+      }
+      // ② 不是槽位选项：当**动作组**播一次。这一段是临时表演，记下当前动作、演完接回去。
+      motion.current.resumeAfter(previousMotionPlan());
       const groups = motion.current.groups();
       const entry = (petRef.current?.motions ?? []).find((item) => item.label === label);
       const group = entry !== undefined && Array.isArray(groups[entry.group]) ? entry.group : undefined;
       if (group !== undefined) {
         motion.current.playOnce(group, 0, { kind: "tap" });
+        armReactionRevert();
         return true;
       }
       if (Array.isArray(groups[label])) {
         motion.current.playOnce(label, 0, { kind: "tap" });
+        armReactionRevert();
         return true;
       }
+      // ③ 当成表达式闪一下。表达式不碰身体，所以刚才那份"接回"要撤掉（否则会空接一次）。
+      motion.current.resumeAfter(null);
       flashExpression(label);
+      armReactionRevert();
       return true;
-    }, [flashExpression]);
+    }, [chooseSlotOption, flashExpression]);
+
+    /**
+     * 她现在演的是什么（用于"反应演完接回来"）。
+     *
+     * 只认**槽位动作**：`currentGroup` 是引擎当前的动作组，而它的选项在 `expressionSlots`
+     * 里按标签反查 —— 拿到**同一个选项**才能把 `persist` / `hold` 原样带回去（举着的手
+     * 靠 `persist` 才不会被看门狗放下）。查不到就返回 null（回待机，和以前一样）。
+     *
+     * ⚠️ 刻意用**函数声明**：`runReaction` 在上面就要用它，`const` 会 TDZ（和
+     * `chooseSlotOption` 同一个理由）。
+     */
+    function previousMotionPlan() {
+      const group = motion.current.currentGroup();
+      if (typeof group !== "string" || group === "" || group === "Idle") return null;
+      for (const slot of petRef.current?.expressionSlots ?? []) {
+        for (const option of slot.options ?? []) {
+          if (option.motion !== group) continue;
+          return {
+            group,
+            index: 0,
+            options: { kind: "slot", hold: true, persist: true },
+          };
+        }
+      }
+      return null;
+    }
     runReactionRef.current = runReaction;
 
     /**
@@ -4955,8 +6160,12 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
      * @param {boolean} satisfy 手动点选时传 true：前提由插件补齐（点自拍会先把手机
      *   掏出来）。摸鱼/相位这些自动路径**不能**传 —— 那会绕过用户配的权重，
      *   变成"她自己去掏手机再拍照"。
+     *
+     * ⚠️ 这里刻意用**函数声明**（不是 `const … = useCallback`）：`runReaction` 在上面、
+     * 又要调它（互动反应 = 换一个槽位的选项）。`const` 有 TDZ，首次渲染就会
+     * "Cannot access before initialization"；函数声明会提升，所以顺序随便放。
      */
-    const chooseSlotOption = useCallback((slot, option, satisfy) => {
+    function chooseSlotOption(slot, option, satisfy) {
       // 关系（同时 / 前提）是按**选项**生效的：用户在这里改过的内容必须对面板点选、
       // 摸鱼抽中、相位抽中同时成立，所以统一在这一个入口合成。
       option = effectiveOption(slot.id, option);
@@ -5118,7 +6327,7 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       // choice the user reverses from this panel (or with 归位), and expiring it
       // after a few seconds would make the panel feel broken.
       window.clearTimeout(expressionTimer.current);
-    }, [applyExpressions]);
+    }
 
     // The fidget effect below subscribes on a different dependency list, so it
     // reaches the chooser through a ref. Without this assignment the ref keeps
@@ -5154,12 +6363,16 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
      * 对不上就当没存过，不要凭空造一个选项出来）。
      */
     const outfitRestoredRef = useRef(false);
-    useEffect(() => {
-      if (outfitRestoredRef.current || !ready) return;
-      if (slotByIdRef.current.size === 0) return;
-      outfitRestoredRef.current = true;
-      const saved = readOutfit();
-      if (saved === null) return;
+    /**
+     * 把一份装扮存档应用到槽位上（**同一份清洗逻辑**，两个入口共用）。
+     *
+     * 两个入口：① 启动时读本地存档；② 模块级的轮询从宿主拉回"另一个窗口改的那份"。
+     * 校验必须一致 —— 写两份的话，一边校验一边不校验，就会出现"某个窗口能存进去、
+     * 另一个窗口把它丢掉"的怪现象。
+     */
+    const applyOutfit = (saved) => {
+      if (saved === null || typeof saved !== "object") return false;
+      if (slotByIdRef.current.size === 0) return false;
       const chosen = Object.assign({}, slotSelectionsRef.current);
       let restored = false;
       for (const id of OUTFIT_SLOTS) {
@@ -5169,9 +6382,19 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         chosen[id] = label;
         restored = true;
       }
-      if (!restored) return;
+      if (!restored) return false;
       slotSelectionsRef.current = chosen;
       commitPinsRef.current();
+      return true;
+    };
+    // 挂上模块级的桥：宿主的改动由轮询拉回来后走这里（见 applyOutfitRef 的注释）。
+    applyOutfitRef.current = applyOutfit;
+
+    useEffect(() => {
+      if (outfitRestoredRef.current || !ready) return;
+      if (slotByIdRef.current.size === 0) return;
+      outfitRestoredRef.current = true;
+      applyOutfit(readOutfit());
     }, [ready]);
 
     // ---- session activity (#4) -----------------------------------------
@@ -5553,6 +6776,10 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     // Interaction bookkeeping lives above the effects that read it, so the
     // idle-fidget scheduler can tell "left alone" from "being handled".
     const dragState = useRef(null);
+    // 诊断读口：按住那一刻路由用的三个答案（尾鳍点不到这类问题要能直接看见它们，
+    // 而不是从"她说了什么"倒推）。
+    const lastPressRef = useRef(null);
+
     // Last time the user touched the pet; the idle-fidget timer (#6) measures
     // quiet time from here so a fidget never fires under the user's cursor.
     const lastInteraction = useRef(Date.now());
@@ -5616,6 +6843,17 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
      * hidden and the stage keeps its old full-box behaviour.
      */
     const [maskPath, setMaskPath] = useState("");
+    /**
+     * `[data-hit]` 真正用的路径 = 轮廓快照 + **尾巴那一块矩形**（跟着摆动更新）。
+     *
+     * 为什么要并：轮廓是开机从渲染画布抓一次的静态网格，而尾鳍一直在摆 —— 摆出去的那一
+     * 瞬间，点击落在 `clip-path` 之外、事件直接穿透到页面（实测 `elementFromPoint=HTML`，
+     * 而 `hitsMask` / `hitsTail` 都说是她）。这正是用户报的"尾巴一直在摆动，摸尾巴很难
+     * 点到"。并一条矩形只多 20 来个字符，而且**只有一层 DOM**：再叠一层会和主层抢事件，
+     * 落哪一层取决于 z 序与更新时间，那种不确定性极难查。
+     */
+    const [tailPath, setTailPath] = useState("");
+    const hitPath = tailPath === "" ? maskPath : (maskPath === "" ? tailPath : maskPath + tailPath);
     const pendingPhase = useRef(null);
     // Published by the stream effect so the (earlier-declared) subscription can
     // flush a deferred phase; a ref avoids a declaration-order dependency.
@@ -5696,11 +6934,76 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       };
     }, [panelOpen]);
 
+    /**
+     * 显示层：这只宠物现在归谁管。
+     *
+     * 宠物有两条呈现路径 —— **页面内**（就是这里）与**桌面上**（一个原生窗口进程）。
+     * 两边都可能活着，所以按 `mode` + 桌面端心跳算出一个 owner；**owner 不是我就让位**
+     * （判据见 `rootStyle` 调用处：两边跑的是同一段客户端代码，"我是谁"要自己判断）。
+     *
+     * 让位用的是 `visibility: hidden` + `pointer-events: none`，**不是 `display: none`**：
+     * 后者会让元素尺寸变 0（`getBoundingClientRect()` 全零），而命中遮罩、自适应缩放都
+     * 靠尺寸算 —— 藏起来再显示回来时判定就歪了。`visibility` 保留布局，一藏一显不留后遗症。
+     *
+     * **轮询不在这里**：它由模块级单例 `ensureLayerPolling()` 负责。写在这个组件的 effect
+     * 里曾经导致一个很隐蔽的 bug —— 选了"桌面"之后这个组件让位/不渲染，轮询随之停掉，
+     * 于是设置页那一行永远停在旧文本（要重开设置页才更新）。观测者不能是要观测的那个东西。
+     */
+    useEffect(() => {
+      ensureLayerPolling();
+    }, []);
+
     const onContextMenu = useCallback((event) => {
       event.preventDefault();
       setPanelOpen(true);
     }, []);
 
+    /**
+     * 桌面端专属：**托盘菜单**驱动的两个动作。
+     *
+     * 桌宠没有任务栏按钮（壳把窗口设成不进任务栏），托盘是唯一的常驻入口。所以
+     * "设置…"和"归位"这两项要把动作送到页面里来：
+     *
+     *   * `settings` → 打开面板并切到设置页签（等于替用户点开它）；
+     *   * `reset`    → 位置与大小回到默认，并演一下"归位"的反应。
+     *
+     * **两条通道都接**：
+     *   * `window.__petCommand(name)` —— 桌面壳的**命令队列**（页面每 33ms 取一次）；
+     *   * `pet://reset` / `pet://settings` DOM 事件 —— 网页端与将来可能有的桥。
+     *
+     * 为什么命令走 HTTP 而不是 Tauri 的窗口事件：`window.emit()` **不发 DOM 事件**、
+     * 只走 IPC，而外部页面没有 `window.__TAURI__`（壳里 `withGlobalTauri: false`）。
+     * 原来只监听 DOM 事件，于是托盘里"设置""归位"点了**永远没反应**（用户报过）。
+     */
+    useEffect(() => {
+      if (!desktopNow()) return undefined;
+      const onReset = () => {
+        // 默认位置就是首次打开时那套（面板右下角），见 pos 的初始化。
+        setSize(DEFAULT_SIZE);
+        setPos({ right: 24, bottom: 0 });
+        saveStored({ size: DEFAULT_SIZE, right: 24, bottom: 0 });
+        lastInteraction.current = Date.now();
+        say(pick(linesNow().reset));
+      };
+      const onSettings = () => {
+        setTab("settings");
+        setPanelOpen(true);
+      };
+      /** 壳的命令队列入口：名字与 DOM 事件同一套。 */
+      const onCommand = (command) => {
+        if (command === "reset") onReset();
+        else if (command === "settings") onSettings();
+      };
+      window.__petCommand = onCommand;
+      window.addEventListener("pet://reset", onReset);
+      window.addEventListener("pet://settings", onSettings);
+      return () => {
+        if (window.__petCommand === onCommand) delete window.__petCommand;
+        window.removeEventListener("pet://reset", onReset);
+        window.removeEventListener("pet://settings", onSettings);
+      };
+    }, [say]);
+
     const onPointerDown = useCallback((event) => {
       if (event.button !== 0) return;
       // A press on a transparent corner only ever starts a drag: it must not
@@ -5717,6 +7020,7 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
         onHead: hitsHead(event.clientX, event.clientY),
         onTail: hitsTail(event.clientX, event.clientY),
       };
+      lastPressRef.current = Object.assign({ at: Date.now(), layer: event.currentTarget?.getAttribute?.("data-tail") !== null ? "tail" : "hit" }, dragState.current);
       setDragging(true);
       try { event.currentTarget.setPointerCapture(event.pointerId); } catch { /* not capturable */ }
     }, [hitsModel, hitsHead, hitsTail]);
@@ -5749,22 +7053,29 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
           });
         } else if (state.onModel) {
           lastInteraction.current = Date.now();
-          // **摸头优先于摸尾巴**：两者区域可能重叠（尾巴/翅膀挂件在身后，几何上会伸到
-          // 头部附近），先判头才符合直觉 —— 用户报的"摸头出的是摸尾巴的效果"就是
-          // 原来先判尾巴造成的。隐藏配件的问题另有 isDrawableVisible 兜着。
-          if (state.onHead && FLAGS.patEnabled) {
+          // **摸尾巴优先于摸头**（2026-09 按用户要求翻回来的）。
+          //
+          // 历史：最早就是"先判尾巴"，用户报"摸头出的是摸尾巴的效果" → 改成"先判头"。
+          // 当时的原因是**失败模式**：`hitsTail` 把 16 块名字带"尾/翅"的几何全算尾巴，
+          // 其中 11 块是**可换配件**（几何一直留在原地、横跨全身），于是尾鳍上 86.6% 的
+          // 点同时算头（`cdp-interact` 里量到的），先判尾巴等于"点在头部也给尾巴反应"。
+          //
+          // 现在那个前提没了：尾鳍已按**贴图**收窄到 5 块真尾鳍（`TAIL_FIN_UV`），实测
+          // 重叠降到 **9%**（网格 32×32：只算头 262、只算尾巴 17、两者都算 29）。而用户
+          // 看到的是"尾巴画在头发上面"—— 点在**看得见的尾鳍**上时，他要的是摸尾巴。
+          // 取舍：那 29 格（头部区域里的一小片）现在会给尾巴反应；换来的是可见尾鳍上的
+          // 点击行为与画面一致。改回去只需把这两个分支换回来。
+          if (state.onTail && FLAGS.tailEnabled) {
+            const list = interactionReactions("tailReactions");
+            if (list.length > 0) runReactionRef.current(pick(list));
+            say(pick(linesNow().tail));
+          } else if (state.onHead && FLAGS.patEnabled) {
             // 摸头：从 `patReactions` 里随机挑一个（默认是 重锤出击 / 问号 / 星星眼），
             // 并且**故意不脸红**。表情类反应是"闪一下"，到点由自动清理收走，
             // 所以摸头不会在用户选的槽位上留下永久表情。
             const list = interactionReactions("patReactions");
             if (list.length > 0) runReactionRef.current(pick(list));
             say(pick(linesNow().pat));
-          } else if (state.onTail && FLAGS.tailEnabled) {
-            // 摸尾巴：判据和摸头同一套（模型自己的三角面），部件集合是 cdi3 里
-            // 命名为尾/鳍/翅/翼 的那些。反应从 pet.json 的 `tailReactions` 里随机。
-            const list = interactionReactions("tailReactions");
-            if (list.length > 0) runReactionRef.current(pick(list));
-            say(pick(linesNow().tail));
           } else {
             // Anywhere else on the character is a lighter acknowledgement —
             // deliberately WITHOUT 重锤出击, which now belongs to the head only.
@@ -5846,6 +7157,8 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     const panel = panelOpen && pet !== undefined
       ? h("div", {
           "data-panel": "",
+          // 桌面端的设置页签需要更宽（见样式表里那条 [data-wide]）。
+          ...(tab === "settings" ? { "data-wide": "" } : {}),
           // Pin the panel once it is on screen (requirement #11).
           //
           // It is anchored to the pet's box, so resizing the pet moved the panel
@@ -5884,9 +7197,17 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
             // DSH 自己的设置页（那一节由 host 注册，和这里共用同一份 store），右键面板
             // 里再放一份，只是"改池子不用翻设置"。用户要求去掉 —— 面板现在只负责
             // 「点一下换个样子」，改数值去设置页。
+            //
+            // **桌面端是例外**：那边没有 DSH 设置页（`ctx.slots` 挂不上），设置正文
+            // 没有别的家 —— 所以只在桌面端把这一页签加回来。守卫见 desktopNow()。
+            desktopNow() ? h("button", {
+              type: "button",
+              "data-tab-settings": "",
+              ...(tab === "settings" ? { "data-on": "" } : {}),
+              onClick: () => setTab("settings"),
+            }, "设置") : null,
           ),
-          h("div", { "data-body": "" }, tab === "slots"
-            // Dress-up slots: one choice each, and choices in different slots
+          h("div", { "data-body": "" }, tab === "slots"            // Dress-up slots: one choice each, and choices in different slots
             // coexist (glasses AND cat ears AND a dark tablecloth).
             ? (pet.expressionSlots ?? []).map((slot) => {
                 // An option is active when every expression it carries is pinned:
@@ -5936,6 +7257,11 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
                   }, entry.count > 1 ? "第 " + (index + 1) + " 段" : "播放")),
                 ),
               ))
+            : tab === "settings"
+            // 桌面端专属：设置正文（和 DSH 设置页那一节是同一个组件、同一份 store）。
+            // 外面这层 `data-settings` 把作用域带进来 —— 面板只有 270→340px 宽，
+            // 样式表里已经为窄容器收过一档列宽。
+            ? h("div", { "data-settings": "", "data-panel-settings": "" }, h(PetSettingsBody, null))
             : null,
           ),
           h("div", { "data-hintrow": "" }, "在宠物身上点右键打开这里 · Esc 或点空白处关闭"),
@@ -5957,13 +7283,25 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     return h("div", {
       [PET_ATTR]: "",
       ref: rootRef,
-      style: rootStyle(size, pos),
+      // **让位判据**：owner 不是我，就把自己藏起来。
+      //
+      // 客户端半区在**两边**都跑（DSH 页面里一份、桌面端窗口里一份），所以"我是谁"要自己
+      // 判断：桌面壳会建 `window.__petDesktop`（页面侧没有这个）。
+      //   * 页面里：所有权在桌面端 → 让位（否则会看见两只）
+      //   * 桌面端：所有权在页面内（用户选了"页面内"）→ 让位
+      // 这两个方向必须都判，否则会出现"两只"或"一只都没有"。
+      style: rootStyle(size, pos, isDesktopShell ? layer.owner !== "desktop" : layer.owner !== "inline"),
       // Observability: the committed action of the motion state machine
       // ('idle' while resting) and the current gaze target, so the pet's
       // behaviour is inspectable without reaching into engine internals.
       "data-motion": motionGroup === "" ? "idle" : motionGroup,
       "data-gaze": gaze,
       "data-phase": phase,
+      // 显示层：owner=desktop 时这一份已经让位（藏在桌面端那只后面）。
+      "data-layer": layer.owner,
+      "data-layer-mode": layer.mode,
+      // 这一份是"页面里"还是"桌面窗口里" —— 让位判据与诊断都靠它。
+      "data-renderer": isDesktopShell ? "desktop" : "page",
       // 宿主主题：面板与气泡的配色 token 按它切（见 CSS 里的 --pp-*）。
       "data-theme": theme,
     },
@@ -5979,10 +7317,16 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
       },
         // Only the silhouette is interactive; everything else in the square
         // canvas stays click-through to the page behind (requirement #5).
+        //
+        // **尾巴那一块要并进这条路径**：轮廓是开机抓一次的静态快照，而尾鳍一直在摆，
+        // 摆出快照的那一瞬间点击会穿透到页面（实测：`elementFromPoint=HTML`，而判定说
+        // 是她）。并一条矩形只多 20 来个字符，比"再叠一层 DOM"更不容易和主层抢事件
+        // —— 两层叠着的时候，落哪一层取决于 z 序与更新时机，那种不确定性正是这一串
+        // 问题里最难查的部分。
         h("div", {
           "data-hit": "",
-          ...(maskPath === "" ? { "data-off": "" } : { style: { clipPath: "path('" + maskPath + "')", WebkitClipPath: "path('" + maskPath + "')" } }),
-          ...(maskPath === "" ? {} : { onPointerDown, onContextMenu }),
+          ...(hitPath === "" ? { "data-off": "" } : { style: { clipPath: "path('" + hitPath + "')", WebkitClipPath: "path('" + hitPath + "')" } }),
+          ...(hitPath === "" ? {} : { onPointerDown, onContextMenu }),
         }),
       ),
       // 气泡的偏移量走 CSS 变量（值，不是布局）：位置规则仍然只写在样式表里。
@@ -6001,8 +7345,21 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
 
   /** Positioning lives on the pet's own root div, so it works whether it is
    * reached through the React container or not. */
-  function rootStyle(size, pos) {
-    return { width: size, height: size, right: pos.right, bottom: pos.bottom };
+  function rootStyle(size, pos, yieldToOther) {
+    const style = { width: size, height: size, right: pos.right, bottom: pos.bottom };
+    if (yieldToOther === true) {
+      // 让位给**另一份**实现：**不用 display:none**（尺寸会变 0，命中遮罩与自适应缩放都
+      // 靠它算，藏一次再显示判定就歪了）。visibility 保留布局，pointer-events 顺带让点击穿过去。
+      //
+      // ⚠️ 判据是"owner **不是**我"，不是"owner 是桌面端"。
+      // 客户端半区在**两边**都跑：页面里一份、桌面端的窗口里一份，而两边跑的是同一段
+      // 客户端代码。所以"owner === desktop"在**桌面端那一份里**也为真 —— 写成那样会把
+      // 唯一该显示的那只藏起来（实测：窗口可见、canvas 也在画、就是 `visibility: hidden`，
+      // 用户看到的是"桌面上什么都没有"）。
+      style.visibility = "hidden";
+      style.pointerEvents = "none";
+    }
+    return style;
   }
 
   // --------------------------------------------------------------- mount
@@ -6566,8 +7923,118 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     );
   }
 
-  function PetSettingsBody() {
+  /**
+   * 显示层：桌宠在**页面内**还是**桌面上**。
+   *
+   * 三个选项就是 `pet-desktop.json` 的 `mode`：`auto` 谁在跑听谁的、`inline` 永远在页面里、
+   * `desktop` 永远在桌面上（没跑就拉起）。改完 POST 给宿主半区 —— 它负责拉起/收掉桌面端
+   * 并写偏好文件；**页面只读不写**，两个写者会互相擦。
+   *
+   * 这一整张卡只在"这个平台有桌面版"时才有意义；没有的话（比如 macOS 还没构建）给一行
+   * 说明而不是三个点了没反应的按钮。
+   */
+  function LayerControls() {
     useSettings();
+    const layer = useLayerState();
+    const [busy, setBusy] = useState(false);
+    const [note, setNote] = useState("");
+    const current = layer;
+    const options = [
+      ["auto", "自动", "桌面端在跑就用桌面，否则留在页面里"],
+      ["inline", "页面内", "永远在 DSH 页面里（随 DSH 启停）"],
+      ["desktop", "桌面", "永远在桌面上；没跑就拉起一个"],
+    ];
+    const choose = (mode) => {
+      setBusy(true);
+      setNote("正在切换…");
+      fetch(API + "/layer", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ mode }),
+      }).then((response) => response.json()).then((payload) => {
+        setBusy(false);
+        // **选「桌面」但没成，必须说清楚为什么** —— 否则症状就是"点了没反应"。
+        // 两种最常见：二进制不在（还没装 / 还没构建）、拉起来了但没起来。
+        //
+        // 这条是补的：第一版只把 `desktopRunning` 翻成一句陈述句（"桌面端没在跑。"），
+        // 用户点完看到的字和点之前几乎一样，于是合理地报"啥变化都没有"。
+        if (payload?.ok !== true) {
+          setNote("切换失败：" + (payload?.error ?? "未知"));
+          return;
+        }
+        if (payload.mode === "desktop" && payload.desktopRunning !== true) {
+          setNote(payload.binary?.found === true
+            ? "桌面端拉起来了，但它没在 6 秒内报活 —— 看看是不是被系统拦住了（未签名的 exe 会被 SmartScreen 拦）"
+            : "桌面端二进制不在" + (payload.binary?.hint === undefined ? "" : "：" + payload.binary.hint));
+          return;
+        }
+        setNote(payload.desktopRunning === true ? "桌面端已在跑。" : "已切回页面内。");
+      }).catch((error) => {
+        setBusy(false);
+        setNote("切换失败：" + String(error && error.message));
+      });
+    };
+    const binary = current.binary ?? {};
+    const supported = binary.supported !== false;
+    const download = current.download ?? { state: "idle" };
+    const missing = supported && binary.found !== true;
+    /** 惰性下载：二进制不在时那个按钮做的事（先回话、后台下，进度靠每秒轮询带回来）。 */
+    const fetchBinary = () => {
+      setNote("正在下载桌面端（约 5MB）…");
+      fetch(API + "/layer", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ action: "download-desktop" }),
+      }).then((response) => response.json()).then((payload) => {
+        setNote(payload?.download?.started === true ? "下载已开始…" : "下载没能开始：" + (payload?.download?.reason ?? "未知"));
+      }).catch((error) => setNote("下载请求失败：" + String(error && error.message)));
+    };
+    const downloadLine = download.state === "downloading"
+      ? "正在下载…"
+      : download.state === "done"
+        ? "下载完成，已就绪"
+        : download.state === "failed"
+          ? "下载失败（" + String(download.reason ?? "未知") + (download.detail === null || download.detail === undefined ? "" : "：" + download.detail) + "）"
+          : null;
+    return h("div", { "data-setting": "layer" },
+      // 三个选项是**药丸按钮**：形状与反应候选那排 chips 共用同一条规则，所以外面要套一层
+      // `[data-reaction-set]`（设置页作用域的 chips 样式挂在它下面）。少这层壳的表现是
+      // "三个按钮挤成一行字"，实测过一次。
+      h("div", { "data-reaction-set": "", "data-layer-options": "" },
+        h("div", { "data-chips": "" },
+          ...options.map(([mode, label, hint]) => h("button", {
+            key: mode,
+            type: "button",
+            title: hint,
+            disabled: busy,
+            ...(current.mode === mode ? { "data-on": "" } : {}),
+            "data-layer-mode": mode,
+            onClick: () => choose(mode),
+          }, label)))),
+      // 状态行：**只在这里**说一次"二进制在不在"，不要和选项混在一段里。
+      //
+      // 缺二进制时给一个**能点的下一步**：只说"不在"，用户除了盯着看没有别的动作可做 ——
+      // 这正是"点了桌面没反应"那次投诉的另一半。
+      h("div", { "data-note-inline": "", "data-layer-status": "" },
+        [supported ? null : "本平台还没有桌面版构建",
+          missing ? "桌面端二进制不在" : null,
+          supported && binary.found === true
+            ? "桌面端：" + (current.desktopRunning ? "运行中（已接管）" : "没在跑") + "（" + String(binary.source ?? "") + "）"
+            : null,
+          downloadLine,
+          note === "" ? null : note,
+        ].filter((line) => line !== null).join(" · ")),
+      missing ? h("div", { "data-layer-actions": "" },
+        h("button", {
+          type: "button",
+          disabled: busy || download.state === "downloading",
+          "data-layer-download": "",
+          onClick: fetchBinary,
+        }, download.state === "downloading" ? "下载中…" : "下载桌面端（约 5MB）")) : null,
+    );
+  }
+
+  function PetSettingsBody() {    useSettings();
     const card = (key, title, hint, body) => h("div", { key, "data-card": key },
       h("div", { "data-card-head": "" },
         h("span", { "data-card-title": "" }, title),
@@ -6578,6 +8045,8 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
     return [
       ...TUNING_GROUPS.filter((group) => !TUNING_GROUPS_INLINE.includes(group.id)).map((group) => card(
         "tune-" + group.id, group.label, group.hint, h(TuningControls, { group: group.id }))),
+      // 显示层放最上面：它是"这只宠物在哪"的问题，比手感/池子更先要回答。
+      card("layer", "显示位置", "页面内 / 桌面上", h(LayerControls, null)),
       card("phases", "会话相位", "每个相位一组池子", h(PhaseControls, null)),
       // 「摸鱼节奏」（多久摸一次）和「摸鱼」（摸鱼做什么）是同一件事的两半，原来
       // 被「会话相位」隔成两张卡，调摸鱼要上下跳。合成一张：节奏在上、池子在下。
@@ -6628,9 +8097,31 @@ window.__ModuleLoader__.load({ id: "dsh-pet-live2d", factory: (require) => {
 
   function apply(ctx) {
     ensureStyle();
-    // 设置值在模块作用域，客户端启动时读一次存档就够了。
+    // 先按本地存档起来（宿主不在时这就是全部）。
     restoreTuning();
     restoreOverrides();
+    // 再问宿主要"共享的那一份"：桌面端与 DSH 是两个 origin，localStorage 互不可见，
+    // 所以跨窗口一致只能靠宿主。拉回来会覆盖本地（宿主是权威），并广播给两个界面。
+    const applyRemote = (payload) => {
+      applyShared(payload, {
+        tuning: (value) => restoreTuning(value),
+        overrides: (value) => {
+          restoreOverrides(value);
+          notifySettings();
+        },
+        outfit: (value) => {
+          // 装扮是"槽位选择"：灌进去要顺带把 pin 重算一遍（否则画面不跟着变）。
+          // 真正的实现在 `Pet` 里（槽位状态在那边），走模块级的桥。
+          if (applyOutfitRef.current !== null) applyOutfitRef.current(value);
+          notifySettings();
+        },
+      });
+    };
+    void pullShared(applyRemote);
+    // 3 秒轮询：另一个窗口改了，这个窗口跟着变。`storage` 事件不跨 origin，只能轮询。
+    if (sharedPoll === 0) {
+      sharedPoll = window.setInterval(() => { void pullShared(applyRemote); }, SHARED_POLL_MS);
+    }
     applySettings(ctx);
     // Takeover: an earlier instance — a hot reload, or one left behind by a
     // crashed reload — must not leave a second floating pet on the page.