dsh-folia 4.6.0 → 4.7.0

package/lib/index.js

@@ -77,11 +77,7 @@ import { assertSubpackagesResolvable, assertSubpackagesResolvableInHost, httpVie
 // `extOf` 反向传给会话段（清单载荷的容器后缀判据 ⇒ 见该文件头）。
 import { createHostSession } from './kernel/host-session.js';
 export { extOf };
-import { registerInventoryRoutes, warmInventorySiteCache } from './routes/inventory.js';
-import { registerModulesRoutes, warmModulesCache } from './routes/modules.js';
-import { registerBootRoutes } from './routes/boot.js';
-import { registerSiteThumbRoutes } from './routes/site-thumb.js';
-import { registerPetsRoutes } from './routes/pets.js';
+import { registerFeatureRoutes, warmFeatureCaches } from './route-registry.js';
 import { installBootInjection } from './boot/index.js';
 import { registerDiagRoutes } from './routes/diag.js';
 // 遮挡消息桥族（上游新增域模块）：hub 处理 x11 遮挡探针，路由对外暴露状态/控制面。
@@ -291,30 +287,17 @@ export function apply(ctx) {
     }
   }
 
-  // 1. Inventory JSON → lib/routes/inventory.js（路径/头/状态码/错误文案逐字未变）。
-  //    `componentsProbe` 是**只读**行状态面（与 3c-6 的 /diag-log 同一个探针、同一批账）：
-  //    浏览器半边按它在 `/inventory` 里的 `components` 字段决定"该组件的界面渲不渲染"
-  //    （ADR-0013 D3 的状态面；形状与失效口径写在那个族的文件头）。
-  registerInventoryRoutes(webServer, {
-    disposers, base: BASE, mediaOriginApi, buildInventory, componentsProbe: componentProbe,
+  // 1. 功能族路由：**注册表驱动**（lib/route-registry.js）。
+  //    装配点不再逐个点名 —— 加一个功能只改注册表，这里永远是同一次调用。
+  //    已迁移：inventory / modules / boot / site-thumb / pets；
+  //    未迁移的族列在 INLINE_ROUTE_FAMILIES（棘轮，只许缩小），仍由下面的显式调用装载。
+  registerFeatureRoutes(webServer, {
+    disposers, base: BASE, log, mediaOriginApi, buildInventory,
+    componentProbe, ensureImagePreview,
   });
-  // 数据模块索引（站点侧声明「有哪些数据模块」）→ lib/routes/modules.js。
-  // 与 inventory 同一套站点基址；读不到就退回内置集合，绝不让面板因为索引文件而空白。
-  registerModulesRoutes(webServer, { disposers, base: BASE });
-
-  // 开机动画 → lib/routes/boot.js（HTTP 面）+ lib/boot/index.js（注入与屏幕脚本）。
-  // 注入是「关就一行都不注」：没有选片时不产生任何脚本、不产生任何请求。
-  registerBootRoutes(webServer, { disposers, base: BASE, log });
-
-  // 站点图片缩略图代理 → lib/routes/site-thumb.js。卡片用 320px 小图，不再每张下 500 KB 原图。
-  registerSiteThumbRoutes(webServer, { disposers, base: BASE, ensureImagePreview, log });
 
   // 启动预热（有意不阻塞）：站点清单与模块索引各拉一次，让第一次打开面板不冷。
-  // 桌宠：自渲染（不依赖第三方宠物插件）—— 站点当分发通道，我们负责安装与绘制。
-  registerPetsRoutes(webServer, { disposers, base: BASE, log });
-
-  warmInventorySiteCache();
-  warmModulesCache();
+  warmFeatureCaches();
   installBootInjection(ctx, (m) => { try { log(m); } catch { /* ignore */ } });
 
   // 3./3a. 派生媒体族路由（源元信息 / 抽帧转码 + 进度 / 视频缩略图）→ lib/routes/media-derived.js。

package/lib/route-registry.js

@@ -0,0 +1,115 @@
+/**
+ * lib/route-registry.js — **功能路由注册表**（宿主侧）。
+ *
+ * 为什么要它：`lib/index.js` 过去逐个 `registerXxxRoutes(webServer, {…})`，加一个功能就得
+ * 在那个 400 行装配文件里挑一处插进去，并保证依赖对象拼对。客户端已经收口成注册表
+ * （`src/features.js`），宿主侧对称过来，装配点就只剩一次循环。
+ *
+ * 纪律（由 `test/verify-route-registry.mjs` 机器校验）：
+ *   · 本表里写出的族**必须在** `lib/routes/` 里真实存在，且 `deps` 只从传入的上下文取键；
+ *   · `INLINE_ROUTE_FAMILIES` 是**尚未迁移**的族（大依赖：mediaMap / hub / 转码器等），
+ *     它是**棘轮**：只许缩小 —— 迁一个删一个，不许往回调；
+ *   · 两表并集必须覆盖 `lib/routes/*.js`（不许有第三处偷偷注册的族）。
+ *
+ * 迁移一个族的步骤：把 `lib/index.js` 里那段调用删掉 → 在 `FEATURE_ROUTE_FAMILIES` 加一条 →
+ * 从 `INLINE_ROUTE_FAMILIES` 删掉 → 跑守卫。
+ */
+
+import { registerInventoryRoutes, warmInventorySiteCache } from './routes/inventory.js';
+import { registerModulesRoutes, warmModulesCache } from './routes/modules.js';
+import { registerBootRoutes } from './routes/boot.js';
+import { registerSiteThumbRoutes } from './routes/site-thumb.js';
+import { registerPetsRoutes } from './routes/pets.js';
+
+/**
+ * 已迁移的功能族。
+ *
+ * `deps(c)` 只从上下文取键 —— 这样"某个族需要什么"是**声明式**的，装配点不需要知道。
+ * 上下文由门面按需提供（见 lib/index.js 的 `registerFeatureRoutes(webServer, { … })`）。
+ *
+ * @type {{ id: string, file: string, register: Function, deps: (c: any) => any, warm?: Function }[]}
+ */
+export const FEATURE_ROUTE_FAMILIES = [
+  {
+    id: 'inventory',
+    file: 'lib/routes/inventory.js',
+    register: registerInventoryRoutes,
+    // 清单族需要"本机清单构建器 + 组件行状态探针 + 媒体源访问器"：三者都是门面现算的，
+    // 所以只能由调用方传进来（族自己拿不到）。
+    deps: (c) => ({
+      disposers: c.disposers,
+      base: c.base,
+      mediaOriginApi: c.mediaOriginApi,
+      buildInventory: c.buildInventory,
+      componentsProbe: c.componentProbe,
+    }),
+    warm: warmInventorySiteCache,
+  },
+  {
+    id: 'modules',
+    file: 'lib/routes/modules.js',
+    register: registerModulesRoutes,
+    deps: (c) => ({ disposers: c.disposers, base: c.base }),
+    warm: warmModulesCache,
+  },
+  {
+    id: 'boot',
+    file: 'lib/routes/boot.js',
+    register: registerBootRoutes,
+    deps: (c) => ({ disposers: c.disposers, base: c.base, log: c.log }),
+  },
+  {
+    id: 'site-thumb',
+    file: 'lib/routes/site-thumb.js',
+    register: registerSiteThumbRoutes,
+    // 缩略图复用内核的 ffmpeg 套件（ensureImagePreview），不自己 spawn。
+    deps: (c) => ({ disposers: c.disposers, base: c.base, ensureImagePreview: c.ensureImagePreview, log: c.log }),
+  },
+  {
+    id: 'pets',
+    file: 'lib/routes/pets.js',
+    register: registerPetsRoutes,
+    deps: (c) => ({ disposers: c.disposers, base: c.base, log: c.log }),
+  },
+];
+
+/**
+ * **尚未迁移**的族（棘轮：只许缩小）。
+ *
+ * 为什么留在门面里：它们的依赖是内核的活对象（mediaMap / occlusionHub / transcodeKit /
+ * sceneFrameSlot / uploadStoreKit …），搬进本表需要把那些对象也传进来，属于另一轮改动。
+ * 这张清单存在的意义是**把"还剩多少"写下来**，守卫据此防止有人往回调。
+ */
+export const INLINE_ROUTE_FAMILIES = [
+  // 每条写「族 id + 门面里的注册函数名」：两者**不总同形**（presets → registerGlassPresetsRoutes），
+  // 靠名字猜会在守卫里制造假红。迁移一个族 = 在 FEATURE_ROUTE_FAMILIES 加一条 + 删这里一行。
+  { id: 'media-bytes', fn: 'registerMediaBytesRoutes' },
+  { id: 'media-derived', fn: 'registerMediaDerivedRoutes' },
+  { id: 'scene-frame', fn: 'registerSceneFrameRoutes' },
+  { id: 'scene-serve', fn: 'registerSceneServeRoutes' },
+  { id: 'scene-media', fn: 'registerSceneMediaRoutes' },
+  { id: 'live-frame', fn: 'registerLiveFrameRoutes' },
+  { id: 'props', fn: 'registerPropsRoutes' },
+  { id: 'occlusion', fn: 'registerOcclusionRoutes' },
+  { id: 'diag', fn: 'registerDiagRoutes' },
+  { id: 'we-assets', fn: 'registerWeAssetsRoutes' },
+  { id: 'upload', fn: 'registerUploadRoutes' },
+  { id: 'presets', fn: 'registerGlassPresetsRoutes' },
+  { id: 'settings', fn: 'registerSettingsRoutes' },
+  { id: 'cache-dir', fn: 'registerCacheDirRoutes' },
+];
+
+/** 按注册表挂载全部已迁移族；`warm` 钩子显式调用（预热是有意不阻塞的）。 */
+export function registerFeatureRoutes(webServer, ctx) {
+  for (const fam of FEATURE_ROUTE_FAMILIES) {
+    fam.register(webServer, fam.deps(ctx));
+  }
+}
+
+/** 启动预热（站点清单与模块索引各拉一次）。失败静默 —— 预热只是优化。 */
+export function warmFeatureCaches() {
+  for (const fam of FEATURE_ROUTE_FAMILIES) {
+    if (typeof fam.warm !== 'function') continue;
+    try { fam.warm(); } catch { /* 预热失败不影响启动 */ }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-folia",
-    "version":  "4.6.0",
+    "version":  "4.7.0",
     "description":  "Folia 壁纸引擎：把本机 Wallpaper Engine 壁纸搬进 DSH 界面（场景实时渲染 / 视频 / 网页），内置液态玻璃与 Folia 吉祥物，并可从自建站点拉取壁纸。单包形态（组件已合并）。",
     "type":  "module",
     "engines":  {
@@ -156,7 +156,8 @@
                   "README.en.md",
                   "README.beginner.md",
                   "lib/components/",
-                  "lib/features.js"
+                  "lib/features.js",
+                  "lib/route-registry.js"
               ],
     "dsh":  {
                 "bundle":  {