dsh-folia 4.6.0 → 4.8.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/lib/settings/ownership.js

@@ -0,0 +1,85 @@
+/**
+ * lib/settings/ownership.js — **设置键归属清单**（每个键属于哪个功能）。
+ *
+ * 为什么要有它：`lib/settings-schema.js` 有 138 个 DEFAULTS 键 / 134 个 KINDS 键，过去"这个键
+ * 属于哪个功能"只存在于人脑里。后果是真实出现过的：加一个功能要往那张 2000 行的表里挑地方插，
+ * 而删一个功能时没人敢删键（不知道还有谁在用）。
+ *
+ * 这张表把归属写成数据，由 `test/verify-settings-ownership.mjs` 机器校验三条：
+ *   ① 每个键**恰好**有一个归属（没归属 = 有人偷偷加键；两个归属 = 归属不清）；
+ *   ② 每条模式都要**真的匹配到东西**（写错了 / 功能删了留着的模式会被判红）；
+ *   ③ 五个功能（wallpaper / playback / appearance / components / system）都非空 ——
+ *      防止有人把整表塞进一个兜底桶。
+ *
+ * 为什么现在只写数据、不拆文件：拆 `settings-schema.js` 要动 DEFAULTS / KINDS / 一堆
+ * 引用这些常量的消毒器，属于高风险改动；先把**归属**固定住，拆分才有对账依据。
+ * 拆分时的目标形态已经写在这里：每个 `files` 条目将来对应 `lib/settings/<id>.js`。
+ */
+
+/** @typedef {{ id: string, name: string, why: string, files?: string[], keys?: string[], prefixes?: string[] }} FeatureKeys */
+
+/** @type {FeatureKeys[]} */
+export const SETTINGS_OWNERS = [
+  {
+    id: 'wallpaper',
+    name: '壁纸',
+    why: '壁纸本体的显示参数：着色/裁切/图层几何/场景帧/评分与来源筛选/自定义属性。',
+    files: ['lib/routes/inventory.js', 'src/quick-panel.js', 'src/picker-model.js'],
+    keys: [
+      'scrim', 'border', 'blur', 'wallpaperBlur', 'wallpaperOpacity', 'objectFit', 'flip',
+      'backgroundBrightness', 'backgroundContrast', 'backgroundSaturate',
+      'layerPositionX', 'layerPositionY', 'layerScale',
+      'hiddenIds', 'contentRatingFilter', 'typeFilter', 'sourceFilter', 'pickerLayout',
+      'sceneFrameUrl', 'sceneLive', 'sceneLiveFps', 'sceneLiveFailures',
+      'customFrames', 'frameVariants', 'userProps', 'edgeCompat',
+    ],
+  },
+  {
+    id: 'playback',
+    name: '播放',
+    why: '播放与轮换的时序：轮换间隔/过场、倍速、帧率上限、声音、暂停策略。',
+    files: ['src/client-rotation.js', 'src/client-audio-playback.js', 'src/panel-tabs-advanced.js'],
+    keys: [
+      'rotationEnabled', 'rotationInterval', 'rotationGroupId', 'rotationGroups', 'rotationSeeded',
+      'switchTransition', 'switchTransitionDir', 'switchTransitionSpeed',
+      'playbackRate', 'fpsCap', 'videoVolume', 'videoAudioEnabled',
+      'pauseOnHidden', 'pauseOnBlur', 'pauseOnBattery', 'liveBootDelay',
+    ],
+  },
+  {
+    id: 'appearance',
+    name: '外观',
+    why: '玻璃 / 主题 / 字体 / 配色 / 胶囊与侧栏装饰：改的是界面自身的观感。',
+    files: ['src/glass.js', 'src/glass-panel.js', 'src/theme-follow.js', 'src/system-fonts.js'],
+    prefixes: ['glass', 'sidebar', 'titlebar', 'capsule', 'leftSidebar', 'rightSidebar', 'uiColor', 'theme', 'font', 'accent', 'chatGlass', 'extraGlass', 'rope', 'caretColor', 'globalFamily', 'componentFonts', 'noticeSeen'],
+  },
+  {
+    id: 'components',
+    name: '可选组件（fx / parallax / 头像 / 立绘）',
+    why: '七个组件行各自的外观参数：点击拖尾、3D 视差、自定义头像与立绘。',
+    files: ['lib/components/fx/index.js', 'lib/components/parallax/index.js', 'lib/components/mascot-avatar/index.js'],
+    prefixes: ['fx', 'parallax', 'avatar', 'mascotImage'],
+  },
+  {
+    id: 'system',
+    name: '系统',
+    why: '不属于任何单一功能的全局项：设置表版本、皮肤互操作标记、媒体适配目标。',
+    files: ['lib/kernel/config.js', 'lib/kernel/host-kernel.js'],
+    keys: [
+      'settingsVersion', 'skinYieldRestoreId', 'skinYieldRestoreRotation',
+      'adapterTarget', 'mediaIntegration', 'audioSource', 'mediaLyricsOnline',
+      'thinkingGlass', 'thinkingNative',
+      // `id` 不是"设置"而是设置记录的标识字段（DEFAULTS 里与真实设置同形存在）。
+      'id',
+    ],
+  },
+];
+
+/**
+ * 「兜底键」的显式豁免：没有任何模式匹配、且确实只给系统用的少数键。
+ *
+ * ⚠️ 这张表是**棘轮**：只许缩小。往这里加一条 = 又有一个键没人负责。
+ */
+export const UNOWNED_WHY = {
+  // 目前为空：所有键都能被上面的模式覆盖。
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-folia",
-    "version":  "4.6.0",
+    "version":  "4.8.0",
     "description":  "Folia 壁纸引擎：把本机 Wallpaper Engine 壁纸搬进 DSH 界面（场景实时渲染 / 视频 / 网页），内置液态玻璃与 Folia 吉祥物，并可从自建站点拉取壁纸。单包形态（组件已合并）。",
     "type":  "module",
     "engines":  {
@@ -156,7 +156,9 @@
                   "README.en.md",
                   "README.beginner.md",
                   "lib/components/",
-                  "lib/features.js"
+                  "lib/features.js",
+                  "lib/route-registry.js",
+                  "lib/settings/"
               ],
     "dsh":  {
                 "bundle":  {
@@ -195,7 +197,8 @@
                     "test:pets":  "node test/pets-http.mjs",
                     "test:pets-layer":  "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"
+                    "audit":  "node test/run-audit.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/verify-route-registry.mjs \u0026\u0026 node test/verify-settings-ownership.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",