@dsh-skin-studio/gallery

DSH Skin Studio 皮肤中心 —— 浏览 / 试穿 / 应用 / 上传皮肤的 Cordis 客户端插件。

实现依据：docs/FRONTEND_REQUIREMENTS.md（组件结构、交互逻辑、验收标准）+ docs/FANREN_SKINS_DESIGN.md（5 款凡人修仙传皮肤的配色与切换特效）。

快速开始（demo 宿主）

cd packages/gallery
pnpm install
pnpm dev          # http://localhost:5173

demo（dev/）用 mock ClientContext 模拟 DSH 宿主：官方 ctx.theme 语义的 ThemeRuntime + ThemePresenter 镜像、侧边栏 shell。内置 7 款皮肤的主题定义 从 packages/skins/* 的 skin.json + src/index.ts 镜像注册（见 src/client/registry/builtinSkins.ts），因此试穿 / 应用 / 切换特效在 demo 里与真实宿主行为一致。皮肤图片资源经 vite 中间件映射 /skins/{id}/assets/* → packages/skins/{id}/assets/*，与 FANREN_SKINS_DESIGN.md 的资源路径约定一致。

命令

命令	说明
pnpm dev	demo 宿主开发服务器
pnpm build	库构建 → lib/index.js + lib/style.css（vite lib mode）
pnpm typecheck	tsc --noEmit（strict，零报错）
pnpm test	vitest：内置清单 / 校验器 / zip 解压 / 上传全链路

结构

src/
├── index.ts                    # 包入口，re-export apply()
├── client/
│   ├── index.tsx               # apply(ctx)：侧边栏注册 + 全局浮层挂载 + disposer
│   ├── GalleryPanel.tsx/.css   # 界面一：画廊（搜索/Tab/网格/上传/试穿/应用）
│   ├── SkinCard.tsx/.css       # 卡片 + 吉祥物 4 帧动画（steps(1)，1.2s）
│   ├── SkinDetailModal.tsx/.css# 界面二：详情（hero 立绘/配色 swatch/Token 列表）
│   ├── UploadDropZone.tsx/.css # 网格末尾上传格（点击/拖拽 .zip）
│   ├── MascotFloat.tsx/.css    # 应用后的右下角吉祥物浮层（160×160）
│   ├── TransitionFx.tsx/.css   # 切换过渡：全屏一闪 + 5 款专属特效
│   ├── Modal.tsx/.css          # 自实现 Modal（见下方「设计决策」#1）
│   ├── Toast.tsx/.css          # 底部 toast（动作按钮 / duration 0 常驻）
│   ├── icons.tsx               # 全部 SVG 图标（无 emoji）
│   ├── hooks.ts                # useThemeSnapshot / usePrefersReducedMotion
│   ├── settings.ts             # settings.mascotEnabled（默认 true）
│   ├── themeBridge.ts          # 上传皮肤的 ThemeDefinition 代注册
│   └── registry/
│       ├── builtinSkins.ts     # 内置 7 款（skin.json + token 表镜像）
│       ├── skinRegistry.ts     # list / upload / validate / install / remove
│       ├── validate.ts         # skin.json 校验（对齐 validate-skins.mjs + 安全规则）
│       └── unzip.ts            # 零依赖 zip 解压（原生 DecompressionStream）
└── shims/dsh-runtime.d.ts      # 官方 SDK 类型 shim（仅类型，构建期擦除）