dsh-pet 0.1.4 → 0.1.6

package/src/client/app.ts

@@ -0,0 +1,488 @@
+// client 半侧「应用逻辑」：由 tsdown 内联进 lib/client.js 的 __ModuleLoader__ factory。
+// 设计：makeFactory() 返回 DSH 的 factory 函数（f(require) => module），
+//       react 通过 factory 的 require 取得（不走 ESM 顶部 import），
+//       以匹配 DSH 的 window.__ModuleLoader__.load({ id, factory }) 加载方式。
+import { pick, randomBetween, pickWeightedCategory } from './pickers';
+import { stripJsonc, buildAnim, buildMinimalAnim, extractDefaultPets, resolvePets } from './config';
+import { CANVAS_H, FEET_Y, HIT_BOX, DRAG_THRESHOLD } from './constants';
+import { petBridge, makePetConfigSection, NS, zh, en } from './settings';
+import type { PetConfigUI } from './settings';
+import type { AnimConfig, Corner } from './types';
+import type * as ReactNS from 'react';
+
+/**
+ * 返回 DSH 插件 factory：`(require) => module`。
+ * 插件三件套（name / inject / apply）都在其返回的 module 上。
+ */
+export function makeFactory(): (require: (mod: string) => any) => any {
+  return (require) => {
+    var module = { exports: {} as any };
+
+    const react: typeof ReactNS = require('react');
+    const { useEffect, useRef, useState } = react;
+    const { jsx: h } = require('react/jsx-runtime');
+
+    // ============================================================================
+    // 内联 CSS —— 注入一次（官方插件标准做法）
+    // ============================================================================
+    const css = [
+      '.dsh-pet-root{position:fixed;z-index:40;pointer-events:none;user-select:none}',
+      '.dsh-pet-root[data-corner="bottom-right"]{right:var(--dsh-pet-mx,24px);bottom:var(--dsh-pet-my,0)}',
+      '.dsh-pet-root[data-corner="bottom-left"]{left:var(--dsh-pet-mx,24px);bottom:var(--dsh-pet-my,0)}',
+      '.dsh-pet-root[data-corner="top-right"]{right:var(--dsh-pet-mx,24px);top:var(--dsh-pet-my,0)}',
+      '.dsh-pet-root[data-corner="top-left"]{left:var(--dsh-pet-mx,24px);top:var(--dsh-pet-my,0)}',
+      '.dsh-pet-stage{position:relative;width:var(--dsh-pet-size,462px);height:calc(var(--dsh-pet-size,462px)*9/16);pointer-events:none}',
+      '.dsh-pet-video{position:absolute;inset:0;width:100%;height:100%;object-fit:contain;pointer-events:none;opacity:0;transition:opacity .18s ease;transform-origin:center}',
+      '.dsh-pet-video.is-front{opacity:1}',
+      '.dsh-pet-hit{position:absolute;pointer-events:auto;cursor:default;z-index:1}',
+      '.dsh-pet-hit.dragging{cursor:grabbing}',
+      '@media (prefers-reduced-motion: reduce){.dsh-pet-video{transition:none}}',
+    ].join('\n');
+    const cssTag = 'dsh-pet/style.css';
+    if (typeof document !== 'undefined' && document.querySelector('style[data-plugin-css="' + cssTag + '"]') === null) {
+      const tag = document.createElement('style');
+      tag.dataset.plugin = 'dsh-pet';
+      tag.dataset.pluginCss = cssTag;
+      tag.textContent = css;
+      document.head.appendChild(tag);
+    }
+
+    // ============================================================================
+    // 动作配置（唯一事实来源 = config.jsonc）
+    // ============================================================================
+    let ANIM: AnimConfig = buildMinimalAnim();
+
+    // ============================================================================
+    // PetCard 组件 —— 单个宠物实例（配置由容器 PetMulti 传入）
+    // ============================================================================
+    function PetCard({ cfg }: { cfg: PetConfigUI }) {
+      // ---- 尺寸（由配置传入；容器/设置页更新后即时跟随）----
+      const [size, setSize] = useState(cfg.size);
+      const halfW = size / 2;
+      const halfH = (size * 9) / 16 / 2;
+
+      // ---- React 状态 ----
+      const [anim, setAnim] = useState(ANIM.idle[0] ?? '');
+      const [once, setOnce] = useState(true);
+      const [facing, setFacing] = useState('left' as 'left' | 'right');
+      const [dragging, setDragging] = useState(false);
+      const [customPos, setCustomPos] = useState<null | { rx: number; ry: number }>(null);
+      // 初始角落与边距（来自配置；可被容器更新覆盖）
+      const [corner, setCorner] = useState<Corner>(cfg.corner);
+      const [margin, setMargin] = useState({ x: cfg.marginX, y: cfg.marginY });
+
+      // 配置变化即时跟随（容器重新合并 / 设置页保存后通过 petBridge.sync 触发）
+      useEffect(() => {
+        setSize(cfg.size);
+        setCorner(cfg.corner);
+        setMargin({ x: cfg.marginX, y: cfg.marginY });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, [cfg.size, cfg.corner, cfg.marginX, cfg.marginY]);
+      const [seq, setSeq] = useState(0);
+
+      // ---- DOM / 状态 refs ----
+      const rootRef = useRef<HTMLDivElement | null>(null);
+      const stageRef = useRef<HTMLDivElement | null>(null);
+      const videoARef = useRef<HTMLVideoElement | null>(null);
+      const videoBRef = useRef<HTMLVideoElement | null>(null);
+      const frontRef = useRef(0);
+      const pendingRef = useRef<null | { anim: string; once: boolean; gen: number }>(null);
+      const genRef = useRef(0);
+      const dragRef = useRef({ active: false, dragging: false, sx: 0, sy: 0, offX: 0, offY: 0 });
+      const justDraggedRef = useRef(false);
+      const animRef = useRef(anim);
+      animRef.current = anim;
+
+      const switchTo = (next: string, nextOnce: boolean) => {
+        if (!next) return;
+        const pending = pendingRef.current;
+        if (pending && pending.anim === next && pending.once === nextOnce) return;
+        const gen = ++genRef.current;
+        pendingRef.current = { anim: next, once: nextOnce, gen };
+        const target = frontRef.current === 0 ? videoBRef : videoARef;
+        const el = target.current;
+        if (!el) return;
+        el.src = '/pet/thumb/' + encodeURIComponent(next) + '.webm';
+        el.loop = !nextOnce;
+        el.muted = true;
+        el.autoplay = true;
+        el.playsInline = true;
+        el.onended = nextOnce ? handleEnded : null;
+        el.load();
+        const onReady = () => {
+          el.removeEventListener('loadeddata', onReady);
+          if (pendingRef.current?.gen !== gen) return;
+          const old = frontRef.current === 0 ? videoARef : videoBRef;
+          el.classList.add('is-front');
+          if (old.current && old.current !== el) old.current.classList.remove('is-front');
+          frontRef.current = frontRef.current === 0 ? 1 : 0;
+          pendingRef.current = null;
+          el.style.transform = facingRef.current === 'right' ? 'scaleX(-1)' : '';
+          el.play().catch(() => {});
+          if (pendingMoveRef.current) startMoveDrive(el);
+        };
+        el.addEventListener('loadeddata', onReady);
+        if (el.readyState >= 2) onReady();
+      };
+
+      // ---- 状态驱动播放 ----
+      useEffect(() => {
+        switchTo(anim, once);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, [anim, once, seq]);
+      useEffect(() => () => stopMove(), []);
+      useEffect(() => {
+        const onResize = () => setCustomPos((prev) => (prev ? { ...prev } : prev));
+        window.addEventListener('resize', onResize);
+        return () => window.removeEventListener('resize', onResize);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, []);
+
+      // ---- 动画链：播完按权重选下一个 ----
+      const pickNext = () => {
+        const roll = Math.random();
+        const wI = ANIM.weights.idle;
+        const wT = ANIM.weights.turn;
+        const wM = ANIM.weights.move;
+        const topEnd = (wI + wT + wM) / 100;
+        let kind = '';
+        let next = '';
+        if (roll < wI / 100) {
+          kind = 'IDLE';
+          next = pick(ANIM.idle, animRef.current);
+          setAnim(next);
+        } else if (roll < (wI + wT) / 100) {
+          kind = 'TURN';
+          next = pick(ANIM.turn, animRef.current);
+          setAnim(next);
+        } else if (roll < topEnd) {
+          if (!tryMove()) {
+            const cat = pickWeightedCategory(ANIM.categories, facingRef.current);
+            kind = cat ? cat.id : 'FALLBACK';
+            next = cat ? pick(cat.actions, animRef.current) : pick(ANIM.idle, animRef.current);
+            setAnim(next);
+          } else {
+            kind = 'MOVES';
+            next = '移动(池内随机)';
+          }
+        } else {
+          const cat = pickWeightedCategory(ANIM.categories, facingRef.current);
+          kind = cat ? cat.id : 'FALLBACK';
+          next = cat ? pick(cat.actions, animRef.current) : pick(ANIM.idle, animRef.current);
+          setAnim(next);
+        }
+        console.log('[dsh-pet] roll=' + roll.toFixed(4) + ' -> [' + kind + '] ' + next);
+        setOnce(true);
+        setSeq((s) => s + 1);
+      };
+
+      const handleEnded = () => {
+        if (dragRef.current.active) return;
+        if (ANIM.turn.includes(animRef.current)) {
+          setFacing((f) => (f === 'left' ? 'right' : 'left'));
+        }
+        if (ANIM.drag.includes(animRef.current) || ANIM.clicks.includes(animRef.current)) {
+          if (ANIM.idle.length) setAnim(pick(ANIM.idle, animRef.current));
+          setOnce(true);
+          setSeq((s) => s + 1);
+          return;
+        }
+        pickNext();
+      };
+
+      // ---- 移动系统 ----
+      const moveRef = useRef<number | null>(null);
+      const moveTokenRef = useRef(0);
+      const pendingMoveRef = useRef<null | { startRatio: number; startYRatio: number; targetRatio: number; dir: number; totalRatio: number; leadSec: number; tailSec: number }>(null);
+      const customPosRef = useRef(customPos);
+      customPosRef.current = customPos;
+
+      const currentCenterX = () => {
+        const cp = customPosRef.current;
+        if (cp) return cp.rx * window.innerWidth;
+        const rootEl = rootRef.current;
+        if (rootEl) return rootEl.getBoundingClientRect().left + halfW;
+        return window.innerWidth - 24 - halfW;
+      };
+      const currentCenterY = () => {
+        const cp = customPosRef.current;
+        if (cp) return cp.ry * window.innerHeight;
+        const rootEl = rootRef.current;
+        if (rootEl) return rootEl.getBoundingClientRect().top + halfH;
+        return window.innerHeight - 20 - halfH;
+      };
+
+      const startMoveDrive = (el: HTMLVideoElement) => {
+        const pm = pendingMoveRef.current;
+        if (!pm || moveRef.current !== null) return;
+        pendingMoveRef.current = null;
+        const { startRatio, startYRatio, targetRatio, dir, totalRatio, leadSec, tailSec } = pm;
+        const duration = Number.isFinite(el.duration) && el.duration > 0 ? el.duration : 10.09;
+        const travelWindow = Math.max(0.1, duration - leadSec - tailSec);
+        const token = ++moveTokenRef.current;
+        const step = () => {
+          if (moveTokenRef.current !== token) return;
+          const t = el.currentTime || 0;
+          const rootEl = rootRef.current;
+          if (rootEl) {
+            const W = window.innerWidth;
+            const H = window.innerHeight;
+            let ratioX;
+            if (t <= leadSec) ratioX = startRatio;
+            else if (t >= duration - tailSec) ratioX = targetRatio;
+            else ratioX = startRatio + dir * totalRatio * ((t - leadSec) / travelWindow);
+            const px = ratioX * W;
+            const py = startYRatio * H;
+            rootEl.style.left = px - halfW + 'px';
+            rootEl.style.top = py - halfH + 'px';
+            rootEl.style.right = 'auto';
+            rootEl.style.bottom = 'auto';
+          }
+          if (t < duration - tailSec) moveRef.current = requestAnimationFrame(step);
+          else {
+            moveRef.current = null;
+            setCustomPos({ rx: targetRatio, ry: startYRatio });
+          }
+        };
+        moveRef.current = requestAnimationFrame(step);
+      };
+
+      const tryMove = () => {
+        if (moveRef.current !== null || pendingMoveRef.current) return true;
+        const actions = ANIM.moves.actions;
+        if (!actions.length) return false;
+        const chosen = actions[Math.floor(Math.random() * actions.length)];
+        const mp = Object.assign({}, ANIM.moves.default, chosen.params || {});
+        const dir = (facingRef.current === 'right') !== ANIM.turn.includes(animRef.current) ? 1 : -1;
+        const W = window.innerWidth;
+        const cx = currentCenterX();
+        const distance = randomBetween(mp.minDist, mp.maxDist);
+        const target = cx + dir * distance;
+        const leftBound = mp.margin + halfW;
+        const rightBound = W - mp.margin - halfW;
+        if (target < leftBound || target > rightBound) return false;
+        pendingMoveRef.current = {
+          startRatio: cx / W,
+          startYRatio: currentCenterY() / window.innerHeight,
+          targetRatio: target / W,
+          dir,
+          totalRatio: Math.abs(target - cx) / W,
+          leadSec: mp.leadSec,
+          tailSec: mp.tailSec,
+        };
+        setOnce(true);
+        setAnim(chosen.name);
+        return true;
+      };
+      const stopMove = () => {
+        pendingMoveRef.current = null;
+        moveTokenRef.current++;
+        if (moveRef.current !== null) {
+          cancelAnimationFrame(moveRef.current);
+          moveRef.current = null;
+        }
+      };
+
+      const facingRef = useRef<'left' | 'right'>(facing);
+      facingRef.current = facing;
+
+      // ---- 点击 vs 拖拽 ----
+      const handlePointerDown = (e: any) => {
+        e.currentTarget.classList.add('dragging');
+        stopMove();
+        e.currentTarget.setPointerCapture(e.pointerId);
+        const rootEl = rootRef.current;
+        let offX = 0;
+        let offY = 0;
+        if (rootEl) {
+          const rr = rootEl.getBoundingClientRect();
+          offX = e.clientX - (rr.left + rr.width / 2);
+          offY = e.clientY - (rr.top + rr.height / 2);
+        }
+        dragRef.current = { active: true, dragging: false, sx: e.clientX, sy: e.clientY, offX, offY };
+      };
+      const handlePointerMove = (e: any) => {
+        const d = dragRef.current;
+        if (!d.active) return;
+        const dx = e.clientX - d.sx;
+        const dy = e.clientY - d.sy;
+        if (!d.dragging) {
+          if (Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
+          d.dragging = true;
+          setDragging(true);
+          setOnce(true);
+          if (ANIM.drag.length) setAnim(pick(ANIM.drag));
+        }
+        const rootEl = rootRef.current;
+        if (rootEl) {
+          rootEl.style.left = e.clientX - d.offX - halfW + 'px';
+          rootEl.style.top = e.clientY - d.offY - halfH + 'px';
+          rootEl.style.right = 'auto';
+          rootEl.style.bottom = 'auto';
+        }
+        const stageEl = stageRef.current;
+        if (stageEl) stageEl.style.transform = 'none';
+      };
+      const handlePointerUp = (e: any) => {
+        const d = dragRef.current;
+        const wasDragging = d.dragging;
+        d.active = false;
+        d.dragging = false;
+        e.currentTarget.classList.remove('dragging');
+        if (wasDragging) {
+          justDraggedRef.current = true;
+          setTimeout(() => {
+            justDraggedRef.current = false;
+          }, 100);
+          setDragging(false);
+          setCustomPos({ rx: (e.clientX - d.offX) / window.innerWidth, ry: (e.clientY - d.offY) / window.innerHeight });
+          const stageEl = stageRef.current;
+          if (stageEl) stageEl.style.transform = 'translateY(' + bottomPad + 'px)';
+          if (ANIM.idle.length) setAnim(pick(ANIM.idle, animRef.current));
+          setOnce(false);
+        }
+      };
+      const handleClick = (_e: any) => {
+        const d = dragRef.current;
+        if (d.active || d.dragging || justDraggedRef.current) return;
+        if (once && !ANIM.idle.includes(animRef.current)) return;
+        stopMove();
+        setOnce(true);
+        if (ANIM.clicks.length) setAnim(pick(ANIM.clicks));
+      };
+
+      // ---- 渲染 ----
+      const bottomPad = (size * (9 / 16) * (CANVAS_H - FEET_Y)) / CANVAS_H;
+      const stageStyle = dragging ? { transform: 'none' } : { transform: 'translateY(' + bottomPad + 'px)' };
+      const rootStyle = customPos
+        ? (() => {
+            const rx = customPos.rx;
+            const ry = customPos.ry;
+            const left = Math.min(Math.max(rx * window.innerWidth - halfW, 0), window.innerWidth - size);
+            const top = Math.min(Math.max(ry * window.innerHeight - halfH, 0), window.innerHeight - (size * 9) / 16);
+            return { left: left + 'px', top: top + 'px', right: 'auto', bottom: 'auto' };
+          })()
+        : {};
+      const commonVideoProps = { muted: true, playsInline: true, autoPlay: true, title: 'dsh-pet' };
+      const hitProps = {
+        className: 'dsh-pet-hit',
+        style: {
+          left: ((HIT_BOX.x0 / 640) * 100) + '%',
+          top: ((HIT_BOX.y0 / 360) * 100) + '%',
+          width: (((HIT_BOX.x1 - HIT_BOX.x0) / 640) * 100) + '%',
+          height: (((HIT_BOX.y1 - HIT_BOX.y0) / 360) * 100) + '%',
+        },
+        onMouseEnter: (e: any) => {
+          if (!dragRef.current.active) e.currentTarget.style.cursor = 'grab';
+        },
+        onMouseLeave: (e: any) => {
+          if (!dragRef.current.active) e.currentTarget.style.cursor = 'default';
+        },
+        onClick: handleClick,
+        onPointerDown: handlePointerDown,
+        onPointerMove: handlePointerMove,
+        onPointerUp: handlePointerUp,
+        onPointerCancel: handlePointerUp,
+        title: 'dsh-pet',
+      };
+      return h(
+        'div',
+        {
+          ref: rootRef,
+          className: 'dsh-pet-root',
+          'data-corner': corner,
+          'data-facing': facing,
+          style: Object.assign(
+            { '--dsh-pet-size': size + 'px', '--dsh-pet-mx': margin.x + 'px', '--dsh-pet-my': margin.y + 'px' },
+            rootStyle,
+          ),
+          children: h('div', {
+            ref: stageRef,
+            className: 'dsh-pet-stage',
+            style: stageStyle,
+            children: [
+              h('video', Object.assign({}, commonVideoProps, { ref: videoARef, className: 'dsh-pet-video is-front' })),
+              h('video', Object.assign({}, commonVideoProps, { ref: videoBRef, className: 'dsh-pet-video' })),
+              h('div', hitProps),
+            ],
+          }),
+        },
+      );
+    }
+
+    // ============================================================================
+    // PetMulti 容器 —— 多开：拉取配置 → 合并默认+用户层 pets → 渲染多个 PetCard
+    // ============================================================================
+    function PetMulti() {
+      const [pets, setPets] = useState<PetConfigUI[]>([]);
+      const [ready, setReady] = useState(false);
+
+      useEffect(() => {
+        let alive = true;
+        (async () => {
+          try {
+            const r1 = await fetch('/pet/config.jsonc');
+            if (!r1.ok) return;
+            const obj: any = JSON.parse(stripJsonc(await r1.text()));
+            ANIM = buildAnim(obj);
+            const defaults = extractDefaultPets(obj);
+            // 用户覆盖层（设置页保存的完整宠物列表）
+            let user: any = {};
+            try {
+              const r2 = await fetch('/pet/config');
+              if (r2.ok && r2.status !== 204) user = await r2.json().catch(() => ({}));
+            } catch { /* 无用户层时忽略 */ }
+            const merged = resolvePets(defaults, user);
+            if (!alive) return;
+            petBridge.current = merged;
+            petBridge.template = defaults.length ? defaults[0] : null;
+            petBridge.sync = (list: PetConfigUI[]) => {
+              setPets(list);
+              petBridge.current = list;
+            };
+            setPets(merged);
+            setReady(true);
+          } catch { /* 失败静默：保持不渲染（或兜底） */ }
+        })();
+        return () => {
+          alive = false;
+          petBridge.sync = null;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+      }, []);
+
+      return ready ? pets.map((p) => h(PetCard, { key: p.id, cfg: p })) : null;
+    }
+
+    // ============================================================================
+    // 插件主体（Cordis 插件三件套）
+    // ============================================================================
+    const name = 'pet';
+    const inject = ['slots', 'locale'];
+    function apply(ctx: any, _config: any) {
+      // 本地化字典（设置页文案）
+      ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-pet: dictionaries');
+      const t = ctx.locale.bind(NS);
+
+      // 宠物 overlay（多开：容器渲染多个 PetCard）
+      ctx.slots.inject('shell.overlay', function* () {
+        yield ctx.slots.register(
+          { name: 'shell.overlay', id: 'pet', order: 1000 },
+          () => h(PetMulti, {}),
+        );
+      });
+
+      // 设置页：「桌宠配置」（大小/位置，保存即时生效）
+      const PetConfigSection = makePetConfigSection({ h, useState, t });
+      ctx.slots.inject('settings.section', function* () {
+        yield ctx.slots.register(
+          { name: 'settings.section', id: 'pet-config', order: 30, label: () => t('nav'), inject: () => ({ t }) },
+          PetConfigSection,
+        );
+      });
+    }
+
+    module.exports = { apply, inject, name };
+    return module.exports;
+  };
+}

package/src/client/config.ts

@@ -0,0 +1,122 @@
+// 配置层：拉取 / 解析 config.jsonc，构建运行时动作配置（唯一事实来源）。
+import { DEFAULT_PETS } from './settings';
+import type { PetConfigUI } from './settings';
+import type { AnimConfig, Corner } from './types';
+
+/** 安全兜底待机名：用于初始渲染 / 配置缺失时宠物不至于空白 */
+export const FALLBACK_IDLE = '待机呼吸休闲';
+/** 移动默认参数（仅当 config.jsonc 未提供 moves.default 时兜底） */
+export const DEFAULT_MOVE_PARAMS: Record<string, number> = {
+  minDist: 60,
+  maxDist: 240,
+  margin: 20,
+  leadSec: 2,
+  tailSec: 2,
+};
+
+/** 剥除 JSONC 注释（行注释 // 与块注释），得到纯 JSON 字符串。仅用于插件自带配置（无含 // 的 URL 值） */
+export const stripJsonc = (src: string): string =>
+  src
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^\\:])\/\/.*$/gm, '$1')
+    .trim();
+
+/** 最小兜底配置：仅当 config.jsonc 缺失时使用，保证宠物不至于空白 */
+export const buildMinimalAnim = (): AnimConfig => ({
+  idle: [FALLBACK_IDLE],
+  turn: [],
+  drag: [],
+  clicks: [],
+  moves: {
+    default: { ...DEFAULT_MOVE_PARAMS },
+    actions: [],
+  },
+  categories: [],
+  weights: { idle: 100, turn: 0, move: 0 },
+});
+
+/** 从 config.jsonc 解析出的对象构建运行时动作配置（缺字段/写错尽量安全兜底） */
+export const buildAnim = (obj: unknown): AnimConfig => {
+  const a = (obj as any)?.animations;
+  const w = (obj as any)?.animationWeights ?? {};
+  const strArr = (x: unknown): string[] => (Array.isArray(x) ? x.map(String).filter(Boolean) : []);
+  const idle = strArr(a?.idle);
+  if (!idle.length) idle.push(FALLBACK_IDLE);
+  const turn = strArr(a?.turn);
+  const drag = strArr(a?.drag);
+  const clicks = strArr(a?.clicks);
+  let mdef: Record<string, number> = { ...DEFAULT_MOVE_PARAMS };
+  let mActs: { name: string; params?: Record<string, number> }[] = [];
+  if (a?.moves && typeof a.moves === 'object') {
+    if (a.moves.default && typeof a.moves.default === 'object') mdef = { ...mdef, ...a.moves.default };
+    if (Array.isArray(a.moves.actions)) {
+      const list = a.moves.actions
+        .filter((x: any) => x && x.name)
+        .map((x: any) => ({ name: String(x.name), params: x.params && typeof x.params === 'object' ? { ...x.params } : undefined }));
+      if (list.length) mActs = list;
+    }
+  }
+  let cats: { id: string; weight: number; noMirror?: boolean; actions: string[] }[] = [];
+  if (Array.isArray(a?.categories)) {
+    const list = a.categories
+      .filter((c: any) => c && c.id && Array.isArray(c.actions) && c.actions.length)
+      .map((c: any) => ({ id: String(c.id), weight: Number(c.weight), noMirror: !!c.noMirror, actions: c.actions.map(String) }));
+    if (list.length) cats = list;
+  }
+  return {
+    idle,
+    turn,
+    drag,
+    clicks,
+    moves: { default: mdef, actions: mActs },
+    categories: cats,
+    weights: {
+      idle: Number(w.idle) >= 0 ? Number(w.idle) : 10,
+      turn: Number(w.turn) >= 0 ? Number(w.turn) : 5,
+      move: Number(w.move) >= 0 ? Number(w.move) : 5,
+    },
+  };
+};
+
+// ============================================================================
+// 多开宠物配置解析（纯函数，不依赖 React）
+// ============================================================================
+/** 支持的角落白名单 */
+export const CORNERS: Corner[] = ['top-left', 'top-right', 'bottom-left', 'bottom-right'];
+
+/** 归一化一个宠物条目（缺字段回落默认） */
+export function normalizePet(p: any): PetConfigUI {
+  const pos = p && p.position && typeof p.position === 'object' ? p.position : {};
+  return {
+    id: String(p && p.id ? p.id : 'main'),
+    size: Number(p && p.size) > 0 ? Number(p.size) : DEFAULT_PETS[0].size,
+    corner: CORNERS.indexOf(pos.corner) !== -1 ? (pos.corner as Corner) : DEFAULT_PETS[0].corner,
+    marginX: Number.isFinite(Number(pos.marginX)) ? Number(pos.marginX) : DEFAULT_PETS[0].marginX,
+    marginY: Number.isFinite(Number(pos.marginY)) ? Number(pos.marginY) : DEFAULT_PETS[0].marginY,
+  };
+}
+
+/** 从 config.jsonc 对象提取默认宠物列表：必须为 pets 数组；缺失/为空回落代码兜底 DEFAULT_PETS */
+export function extractDefaultPets(obj: any): PetConfigUI[] {
+  const arr = obj && Array.isArray(obj.pets) ? obj.pets.filter((p: any) => p && p.id) : [];
+  if (!arr.length) return DEFAULT_PETS.map((p) => ({ ...p }));
+  const seen = new Set<string>();
+  const out: PetConfigUI[] = [];
+  for (const p of arr) {
+    const id = String(p.id);
+    if (!seen.has(id)) {
+      seen.add(id);
+      out.push(normalizePet(p));
+    }
+  }
+  return out.length ? out : DEFAULT_PETS.map((p) => ({ ...p }));
+}
+
+/** 合并最终宠物列表：用户层（{ pets: 完整列表 }）全量替换默认；无用户层回落默认 */
+export function resolvePets(defaults: PetConfigUI[], user: any): PetConfigUI[] {
+  if (user && Array.isArray(user.pets)) {
+    const list = user.pets.filter((p: any) => p && p.id).map(normalizePet);
+    return list.length ? list : defaults; // 用户层空数组视为无覆盖
+  }
+  return defaults;
+}

package/src/client/constants.ts

@@ -0,0 +1,9 @@
+// 画布 / 几何常量：与 640×360 播放变体强耦合，属于运行时几何，不作为配置。
+/** thumb 画布高度 */
+export const CANVAS_H = 360;
+/** thumb 画布上「脚底」的 y 坐标（人物站在 y=330 线上） */
+export const FEET_Y = 330;
+/** 点击/拖拽命中矩形（thumb 640×360 像素坐标） */
+export const HIT_BOX = { x0: 200, y0: 50, x1: 440, y1: 335 };
+/** 拖拽判定阈值（px） */
+export const DRAG_THRESHOLD = 5;

package/src/client/index.ts

@@ -0,0 +1,15 @@
+// client 半侧 bundle 外壳：由 tsdown 构建为 lib/client.js。
+// 必须是一个「普通副作用脚本」——加载时调用 window.__ModuleLoader__.load，
+// 不能包含顶层 ESM export / import（react 由 factory 的 require 取得）。
+import { makeFactory } from './app';
+
+declare const window: {
+  __ModuleLoader__: {
+    load(info: { id: string; factory: (require: (m: string) => any) => any }): void;
+  };
+};
+
+window.__ModuleLoader__.load({
+  id: 'dsh-pet',
+  factory: makeFactory(),
+});

package/src/client/pickers.ts

@@ -0,0 +1,32 @@
+// 纯选择逻辑：不依赖 React / DOM，可独立单测。
+import type { Category } from './types';
+
+/** 从字符串池里等概率随机抽一个；exclude 排除某个名字（避免连续重复） */
+export const pick = <T,>(pool: T[], exclude?: T): T => {
+  const entries = exclude ? pool.filter((n) => n !== exclude) : pool;
+  // 排除后池空（单元素池 + 排除自己）：退回原池抽——宁可重复，也不要返回 undefined
+  const src = entries.length ? entries : pool;
+  return src[Math.floor(Math.random() * src.length)];
+};
+
+/** 生成 [min, max) 区间内的随机整数 */
+export const randomBetween = (min: number, max: number): number =>
+  Math.floor(min + Math.random() * (max - min));
+
+/**
+ * 按权重在分类池中选一个分类；noMirror 分类在镜像(facing=right)时被排除，
+ * 剩余权重自动归一化。分类池为空时返回 null。
+ */
+export const pickWeightedCategory = (categories: Category[], facing: string): Category | null => {
+  const cats = categories.filter((c) => c.actions.length > 0);
+  if (!cats.length) return null;
+  const filtered = cats.filter((c) => !(c.noMirror && facing === 'right'));
+  const eligible = filtered.length ? filtered : cats;
+  const totalW = eligible.reduce((s, c) => s + c.weight, 0) || 1;
+  let t = Math.random() * totalW;
+  for (const c of eligible) {
+    t -= c.weight;
+    if (t <= 0) return c;
+  }
+  return eligible[eligible.length - 1];
+};