dsh-folia 4.4.0 → 4.5.1

package/lib/client.js

@@ -18065,6 +18065,76 @@ window.__ModuleLoader__.load({
 
 				// 仅供单测驱动（构建期内联时会剥掉 export，不影响产物）。
 
+				// ── 内联模块：src/features.js —— 客户端功能注册表：页签条 / 整区面板 / 常驻挂载层。装配点（quick-panel、client.js）只查表，不写功能名（构建期注入；勿手改本段）──
+				/**
+				 * features.js（客户端）— **功能注册表**：页签声明、面板工厂、挂载钩子。
+				 *
+				 * 为什么需要它：加一个功能过去要改五处共享文件（client.js 挂载 / quick-panel 的 QP_TABS 与
+				 * 渲染点 / settings-schema / build-client 的内联表 / lib/index.js 的路由注册）。前两处是纯
+				 * "接线"，写错了症状是「页签在、点开空白」或「渲染层根本没挂」。把这些收成一份声明后：
+				 *
+				 *   · 页签条 = WE_FEATURE_TABS（顺序就是用户看到的顺序）
+				 *   · 整区面板 = WE_FEATURE_PANELS（哪些页签整区交给功能自己的面板）
+				 *   · 常驻层   = WE_FEATURE_MOUNTS（随插件生命周期挂载/卸载的浮动层，例如桌宠）
+				 *
+				 * 谁也别再往 quick-panel 里写 `qpTab === "xxx"` —— 那是把功能名焊死进装配点。
+				 * 判据：test/verify-features.mjs 会检查 quick-panel 里不再出现具体功能分支。
+				 *
+				 * ⚠️ 内联顺序：本文件必须排在**它引用的所有符号之后**（panel-tabs-boot / panel-tabs-pets /
+				 * pet-layer），且排在 quick-panel.js 与 client.js **之前** —— 那两处在模块顶层读本表。
+				 */
+
+				/** 页签条（顺序 = 界面顺序）。label 用 getter：语言切换后能立刻生效。 */
+				const WE_FEATURE_TABS = [
+				  // 开机动画与壁纸并列：它们回答的是同一个问题"开机/桌面看到什么"，不是壁纸的子功能。
+				  { id: "boot", get label() { return weT("开机动画"); } },
+				  { id: "wallpaper", get label() { return weT("壁纸"); } },
+				  { id: "appearance", get label() { return weT("外观"); } },
+				  { id: "playback", get label() { return weT("播放"); } },
+				  // 桌宠是"桌面上多出来的一只东西"，与壁纸/开机动画并列。
+				  { id: "pets", get label() { return weT("桌宠"); } },
+				];
+
+				/**
+				 * 整区面板：这个页签的内容**整个**由功能自己的组件渲染（而不是 quick-panel 内的通用列表）。
+				 * 没登记的页签走 quick-panel 自己的通用布局（壁纸列表 / 外观节 / 播放节）。
+				 */
+				const WE_FEATURE_PANELS = {
+				  boot: BootTabPanel,
+				  pets: PetsTabPanel,
+				};
+
+				/**
+				 * 常驻层：插件挂载时启动、卸载时归还。每个都必须返回 cleanup（或 undefined）。
+				 * 它们自己决定"要不要显示"（例如桌宠要读配置才知道是否启用），装配点不参与判断。
+				 */
+				const WE_FEATURE_MOUNTS = [
+				  { id: "pets", mount: mountPetLayer },
+				];
+
+				/** 页签 → 功能归属（宿主清单 lib/features.js 的客户端镜像，供守卫对账）。 */
+				const WE_FEATURE_TAB_IDS = WE_FEATURE_TABS.map((t) => t.id);
+
+				/**
+				 * 页签底部那枚「去设置里改」的引导条。
+				 *
+				 * 为什么要收进注册表：它原本是 quick-panel 里的一条 `qpTab === "boot"` 分支 —— 属于
+				 * 「功能名焊死进装配点」。功能自己声明自己的引导语，装配点只查表。
+				 * 没声明的页签走 quick-panel 的通用文案（壁纸 / 外观 / 播放那三档是泛型布局，留在原地）。
+				 */
+				const WE_FEATURE_FOOTERS = {
+				  boot: {
+				    get label() { return weT("打开设置 ›"); },
+				    target: "",
+				    get title() { return weT("开机动画的全部参数都在侧栏「壁纸引擎」设置里"); },
+				  },
+				  pets: {
+				    get label() { return weT("打开设置 ›"); },
+				    target: "",
+				    get title() { return weT("桌宠的开关 / 大小 / 声音都在「桌宠」页签里调整"); },
+				  },
+				};
+
 				// ── 内联模块：src/quick-panel.js —— 快捷播放面板（官方侧栏 tab 与低版本抽屉共用同一份内容）：当前壁纸 + 轮播 + 列表快切 + 声音 + 设置入口。列表虚拟滚动（spacer + 可视窗口）（构建期注入；勿手改本段）──
 				/**
 				 * quick-panel.js — 快捷播放面板（侧边栏的**唯一**内容）：当前壁纸 + 轮播 + 三档页签
@@ -18234,15 +18304,9 @@ window.__ModuleLoader__.load({
 				  // 位置在「轮播」之下：当前壁纸与轮播在三档页签下都显示（调外观 / 播放参数时想换一张
 				  // 对照很常见）。与设置页的页签表（PICKER_TABS）是两件事 —— 这里只镜像用户点名要的
 				  // 两页，外加壁纸页。
-				  const QP_TABS = [
-				    // 开机动画放在「壁纸」左边：它和壁纸是并列的两种"开机时看到什么"，不是壁纸的子功能。
-				    { id: "boot", get label() { return weT("开机动画"); } },
-				    { id: "wallpaper", get label() { return weT("壁纸"); } },
-				    { id: "appearance", get label() { return weT("外观"); } },
-				    { id: "playback", get label() { return weT("播放"); } },
-				    // 桌宠是"桌面上多出来的一只东西"，与壁纸/开机动画并列，不是它们的子功能。
-				    { id: "pets", get label() { return weT("桌宠"); } },
-				  ];
+				  // 页签条从**功能注册表**取（src/features.js）：这里不再出现具体功能名。
+				  // 加功能只该动注册表，不该动装配点 —— 否则又变成"每加一个功能改五处"。
+				  const QP_TABS = WE_FEATURE_TABS;
 				  // 页签记忆（同 picker-tab / qp-view 口径：仅 UI 状态，localStorage，不进 config.json）。
 				  const QP_TAB_KEY = "dsh-folia:qp-tab";
 				  /** 读页签偏好；缺失 / 非法回落「壁纸」。 */
@@ -18916,12 +18980,11 @@ window.__ModuleLoader__.load({
 				    // 设置页同名页签 —— 玻璃详细调节仍只在侧栏（本页，折叠块），设置页那边留玻璃预设、
 				    // 全量配置与**字体节**（三次修订后字体节两档都画）；播放页的出图来源 /
 				    // 实时帧仍住设置页。
-				    const foot = qpTab === "boot"
-				      ? {
-				        label: weT("打开设置 ›"),
-				        target: "",
-				        title: weT("开机动画的全部参数都在侧栏「壁纸引擎」设置里"),
-				      }
+				    // 引导条：整区面板类页签的文案由**功能注册表**给（WE_FEATURE_FOOTERS），装配点只查表；
+				    // 外观 / 播放 / 壁纸是泛型布局，文案留在原地。
+				    const featFooter = WE_FEATURE_FOOTERS[qpTab] || null;
+				    const foot = featFooter
+				      ? featFooter
 				      : qpTab === "appearance"
 				      ? {
 				        label: weT("更多外观设置 ›"),
@@ -18954,10 +19017,10 @@ window.__ModuleLoader__.load({
 				      React.createElement("div", { className: tabBodyClass, ref: qpPaneRef },
 				        qpTab === "wallpaper" && userPropsPanelOpen() && propsAvailable
 				          && React.createElement("div", { className: "we-qp__propsview we-qp__propsview--drill" }, renderUserPropsPanel()),
-				        // 开机动画档：整区就是那个面板（它自己管加载/下载/开关）。
-				        qpTab === "boot" && React.createElement(BootTabPanel, null),
-				        qpTab === "pets" && React.createElement(PetsTabPanel, null),
-				        !(qpTab === "wallpaper" && userPropsPanelOpen() && propsAvailable) && qpTab !== "boot" && (qpTab === "appearance"
+				        // 整区面板：由注册表声明哪些页签整块交给功能自己的组件（开机动画 / 桌宠）。
+				        // 装配点只查表，不写功能名 —— 判据见 test/verify-features.mjs。
+				        Boolean(WE_FEATURE_PANELS[qpTab]) && React.createElement(WE_FEATURE_PANELS[qpTab], null),
+				        !(qpTab === "wallpaper" && userPropsPanelOpen() && propsAvailable) && !WE_FEATURE_PANELS[qpTab] && (qpTab === "appearance"
 				          ? qpRenderAppearancePane(sel, {
 				            fontOpen, onToggleFontSection: toggleFontSection,
 				            uiColorOpen, onToggleUiColorSection: toggleUiColorSection,
@@ -32289,9 +32352,13 @@ window.__ModuleLoader__.load({
 		  if (ctx.effect && typeof document !== "undefined") {
 		    ctx.effect(() => installSkinInterop() || undefined);
 		  }
-		  // 3c. 桌宠层：自己拉 /pets/list 决定是否出宠物，随 fiber 注销（不依赖面板打开过）。
-		  if (ctx.effect && typeof document !== "undefined") {
-		    ctx.effect(() => mountPetLayer() || undefined);
+		  // 3c. 常驻层：由**功能注册表**声明（src/features.js 的 WE_FEATURE_MOUNTS）。
+		  // 装配点不再点名具体功能 —— 每个 mount 自己决定要不要显示（例如桌宠先读配置）。
+		  if (typeof WE_FEATURE_MOUNTS !== "undefined") {
+		    for (const feat of WE_FEATURE_MOUNTS) {
+		      if (!ctx.effect || typeof document === "undefined") break;
+		      ctx.effect(() => feat.mount() || undefined);
+		    }
 		  }
 
 		  // 3. Chat-interface rope dock: the draggable pull-cord + glass repo side

package/lib/features.js

@@ -0,0 +1,260 @@
+/**
+ * lib/features.js — **功能清单**（单一真源）。
+ *
+ * 为什么需要这张表：这个插件已经长到 19 个宿主路由文件 + 70 个客户端文件 + 24k 行，
+ * 而"某个功能到底由哪些文件负责"过去只存在于人脑里。后果是真实的：
+ *   · 加一个功能要同时改 client.js / quick-panel.js / settings-schema.js / build-client.mjs
+ *     / lib/index.js 五处接线，漏一处就"功能看着在、点开是空的"；
+ *   · 有的功能（如站点缩略图）横跨 host + client，谁都能往里塞逻辑，边界逐渐糊掉。
+ *
+ * 这张表把"归属"写成数据，并由 test/verify-features.mjs 机器校验：
+ *   ① 表里每个文件都必须真实存在；
+ *   ② `lib/routes/*.js` 里的**每一个文件都必须被且仅被一个功能认领**（不许有孤儿路由）；
+ *   ③ 每个 `tab` 必须真的出现在客户端 QP_TABS 里（不许有幽灵页签）；
+ *   ④ 用到的站点分类必须在这里登记（站点是数据源，分类就是功能的入口）。
+ *
+ * 这张表**不改变运行行为**（运行时仍按各文件自己的注册方式装配），它的价值是：
+ * 让"模块化"变成可失败的判据，而不是口头承诺。下次要加功能，先在这里登记，再动手。
+ */
+
+/**
+ * @typedef {object} Feature
+ * @property {string} id            功能 id（与 tab / 站点分类对齐）
+ * @property {string} name          中文名（界面与文档用）
+ * @property {string} role          这一层负责什么（一句话）
+ * @property {string[]} host        宿主侧文件（相对仓库根）
+ * @property {string[]} client      浏览器侧文件（相对仓库根）
+ * @property {string[]} [tab]       客户端页签 id（没有页签的写 null）
+ * @property {string[]} [site]      使用的站点分类 slug（站点数据源入口）
+ * @property {string[]} [settings]  拥有的设置键前缀（可空）
+ */
+
+/** @type {Feature[]} */
+export const FEATURES = [
+  {
+    id: 'wallpaper',
+    name: '壁纸',
+    role: '本机/上传/站点三源合并成壁纸库；着色、图层、播放与轮换由客户端接管',
+    host: [
+      'lib/routes/inventory.js',
+      'lib/routes/media-bytes.js',
+      'lib/routes/media-derived.js',
+      'lib/routes/scene-frame.js',
+      'lib/routes/scene-media.js',
+      'lib/routes/scene-serve.js',
+      'lib/routes/live-frame.js',
+      'lib/routes/occlusion.js',
+      'lib/routes/props.js',
+      'lib/routes/we-assets.js',
+      'lib/routes/upload.js',
+      'lib/inventory.js',
+      'lib/wallpaper-scan.js',
+      'lib/upload-store.js',
+      'lib/scene-manifest.js',
+      'lib/faststart.js',
+      'lib/mp4-vfs.js',
+      'lib/media/frame-store.js',
+      'lib/media/transcode.js',
+      'lib/media/video-preview.js',
+      'lib/media/image-preview.js',
+      'lib/media/scene-probe.js',
+      'lib/media/mp4-probe.js',
+      'lib/media/media-dirs.js',
+    ],
+    client: [
+      'src/quick-panel.js',
+      'src/picker-modal.js',
+      'src/picker-model.js',
+      'src/picker-props-panel.js',
+      'src/panel-tabs-wallpaper.js',
+      'src/video-layer.js',
+      'src/layer-core.js',
+      'src/live-layer.js',
+      'src/live-layer-watch.js',
+      'src/live-layer-gate.js',
+      'src/live-layer-pointer.js',
+      'src/live-layer-underlay.js',
+      'src/live-layer-diag.js',
+      'src/media-prep.js',
+      'src/client-media-frame.js',
+      'src/client-rotation.js',
+      'src/client-audio-playback.js',
+      'src/occlusion.js',
+    ],
+    tab: ['wallpaper'],
+    site: ['wallpaper'],
+  },
+  {
+    id: 'site',
+    name: '站点数据源',
+    role: '把站点当唯一数据源：清单拉取、分类过滤、缩略图代理、模块索引',
+    host: [
+      'lib/routes/site-thumb.js',
+      'lib/routes/modules.js',
+    ],
+    client: [],
+    tab: [],
+    site: ['wallpaper', 'boot-animation', 'desktop-pet', 'assistant-skin'],
+  },
+  {
+    id: 'boot',
+    name: '开机动画',
+    role: '站点候选 → 并行下载 → 本地目录 → 启动注入播放（脚本在宿主侧注入，不依赖应用挂载）',
+    host: [
+      'lib/routes/boot.js',
+      'lib/boot/index.js',
+    ],
+    client: ['src/panel-tabs-boot.js'],
+    tab: ['boot'],
+    site: ['boot-animation'],
+    settings: ['boot'],
+  },
+  {
+    id: 'pets',
+    name: '桌宠',
+    role: '自渲染：站点/本机宠物 → 安装解包 → canvas 逐帧绘 sprite2d + 动作状态机 + 语音',
+    host: ['lib/routes/pets.js'],
+    client: ['src/panel-tabs-pets.js', 'src/pet-layer.js'],
+    tab: ['pets'],
+    site: ['desktop-pet'],
+    settings: ['pet'],
+  },
+  {
+    id: 'appearance',
+    name: '外观',
+    role: '玻璃、主题、字体、预设、页签样式 —— 纯客户端表现层',
+    host: [
+      'lib/routes/settings.js',
+      'lib/routes/presets.js',
+      'lib/settings-schema.js',
+      'lib/components/fonts/routes/fontsets.js',
+      'lib/components/fonts/routes/system-fonts.js',
+    ],
+    client: [
+      'src/panel-tabs-appearance.js',
+      'src/glass.js',
+      'src/glass-panel.js',
+      'src/glass-surfaces.js',
+      'src/glass-extra.js',
+      'src/theme-follow.js',
+      'src/system-fonts.js',
+      'src/fontset-store.js',
+      'src/preset-store.js',
+      'src/styles-base.js',
+      'src/styles-chrome.js',
+      'src/styles-ext.js',
+      'src/styles-panel.js',
+      'src/styles-quick.js',
+      'src/styles-settings.js',
+      'src/styles-shell.js',
+      'src/styles-sidebar.js',
+      'src/about-assets.js',
+      'src/nav-icon.js',
+    ],
+    tab: ['appearance'],
+  },
+  {
+    id: 'playback',
+    name: '播放',
+    role: '音量、静音、轮换节奏与播放控制（壁纸的播放面，独立页签）',
+    host: [],
+    client: [
+      'src/panel-tabs-advanced.js',
+      'src/effects.js',
+      'src/adapter.js',
+    ],
+    tab: ['playback'],
+  },
+  {
+    id: 'components',
+    name: '可选组件行',
+    role: '上游形态保留的 7 个组件行（fx/parallax/fonts/mascot-avatar/media-bridge/pet-link/about-notice），各自独立装载',
+    host: [
+      'lib/components/fx/index.js',
+      'lib/components/parallax/index.js',
+      'lib/components/fonts/index.js',
+      'lib/components/mascot-avatar/index.js',
+      'lib/components/media-bridge/index.js',
+      'lib/components/pet-link/index.js',
+      'lib/components/about-notice/index.js',
+    ],
+    client: [],
+    tab: [],
+  },
+  {
+    id: 'system',
+    name: '系统',
+    role: '诊断、缓存目录、设置存储、客户端装配骨架（不属于任何单个功能）',
+    host: [
+      'lib/routes/diag.js',
+      'lib/routes/cache-dir.js',
+      'lib/index.js',
+      'lib/kernel/host-kernel.js',
+      'lib/kernel/host-session.js',
+      'lib/kernel/config.js',
+      'lib/kernel/data-dir.js',
+      'lib/diag-trace.js',
+      'lib/cache-dir.js',
+      'lib/serve.js',
+      'lib/http-body.js',
+      'lib/http-lifecycle.js',
+      'lib/json-response.js',
+      'lib/pkg-read.js',
+      'lib/log.js',
+      'lib/notice.js',
+      'lib/host-boot.js',
+      'lib/subpackage-boot.js',
+      'lib/startup-sweep.js',
+      'lib/fs-paths.js',
+      'lib/upload-dir.js',
+      'lib/steam-discovery.js',
+      'lib/shim-seed.js',
+      'lib/we-props.js',
+      'lib/we-focus-guard.js',
+      'lib/media-origin.js',
+      'lib/types/index.d.ts',
+      'lib/types/client.d.ts',
+    ],
+    client: [
+      'src/client.js',
+      'src/api-client.js',
+      'src/persistence.js',
+      'src/extension-registry.js',
+      'src/i18n.js',
+      'src/i18n-copy.js',
+      'src/i18n-copy-core.js',
+      'src/i18n-copy-ext.js',
+      'src/i18n-copy-font.js',
+      'src/i18n-copy-glass.js',
+      'src/i18n-copy-live.js',
+      'src/i18n-copy-panel.js',
+      'src/i18n-copy-pet-link.js',
+      'src/i18n-copy-picker.js',
+      'src/we-base.js',
+      'src/we-cond.js',
+      'src/module-reset.js',
+      'src/focus-handback.js',
+      'src/sidebar-right.js',
+      'src/section-head.js',
+      'src/avatar-import.js',
+      'src/avatar-layer.js',
+      'src/ext-avatar.js',
+      'src/panel-tabs.js',
+      'src/panel-tabs-effects.js',
+      'src/panel-tabs-mascot.js',
+    ],
+    tab: [],
+  },
+];
+
+/** 页签 id → 功能 id（供校验与文档使用）。 */
+export const TAB_OWNERS = FEATURES.reduce((acc, f) => {
+  for (const t of f.tab || []) acc[t] = f.id;
+  return acc;
+}, {});
+
+/** 站点分类 slug → 功能 id。 */
+export const SITE_OWNERS = FEATURES.reduce((acc, f) => {
+  for (const s of f.site || []) acc[s] = f.id;
+  return acc;
+}, {});

package/package.json

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