dsh-folia 3.9.1 → 4.0.0

package/lib/routes/inventory.js

@@ -84,8 +84,13 @@ function rowStatusOf(probe) {
 }
 
 /* ── Folia 站点数据源 ────────────────────────────────────────────────────────
- * 把自建站点（默认 `https://folia-major-3t6.pages.dev`）清单里的条目并进 inventory，
- * 于是「本机 Wallpaper Engine 工坊 + 上传库 + 站点」三者在客户端看来是同一个壁纸库。
+ * 把自建站点（默认 `https://pub-1275321f146e479eaac54948f4cdad6f.r2.dev`）清单里的条目
+ * 并进 inventory，于是「本机 Wallpaper Engine 工坊 + 上传库 + 站点」三者在客户端看来是
+ * 同一个壁纸库。
+ *
+ * 为什么默认值是 folia-5ve.pages.dev：站点后台（D1 + admin）产出 /data/catalog.json，
+ * 素材 `<base>/boot/*`）。旧站 `folia-major-3t6.pages.dev` 已废弃 —— 但**换站不需要改代码**，
+ * 用 `DSH_FOLIA_SITE` 覆盖即可。
  *
  * 契约：
  *   · 地址由 `DSH_FOLIA_SITE` 覆盖；`=off` 关闭整条通道（测试/离线场景用）。
@@ -95,9 +100,39 @@ function rowStatusOf(probe) {
  *   · 产出条目**自带绝对 URL**（`media` / `preview`），客户端 `apiUrl()` 对绝对 URL 原样放行。
  *
  * 站点格式（`<site>/manifest.json`）：`{ images: [{ file, title, url, preview, kind?, animated? }] }`
- * —— 与 `folia-wallpaper-site` 产物一致。
+ * —— 与 `folia-wallpaper-site` 产物一致；`url`/`preview` 可以是相对路径（相对站点基址）。
+ */
+const FOLIA_SITE = 'https://folia-5ve.pages.dev';
+/**
+ * 站点数据源的两个可能形态，按顺序尝试：
+ *   · `/data/catalog.json` —— 站点（D1 + admin）产出的目录，**当前的真源**
+ *   · `/manifest.json`     —— 早期静态清单，保留兼容（站点上没有 catalog 时回退）
+ * 顺序有讲究：catalog 是站点后台维护的，manifest 是我们手写的；两者都在时以站点为准。
+ */
+/**
+ * 站点的**实时接口**。它比静态快照优先：快照只在部署时生成（我们实测过它停在某个时间点，
+ * 而站点后台早就加了新图），接口才是"你传完就能看到"的那条路。
+ *
+ * 形状：`{ ok, data: { items: [...], total, hasMore, nextCursor } }`，按游标分页。
  */
-const FOLIA_SITE = 'https://folia-major-3t6.pages.dev';
+const FOLIA_API_PATH = '/api/public/wallpapers';
+/**
+ * 只要壁纸分类。站点分类不止壁纸（还有 `boot-animation` / `skin-pack` / 桌宠），
+ * 而它们的 `kind` 同样是 `dynamic`/`static` —— 只按类型判会把开机动画当成壁纸拉进来。
+ * 服务端支持 `?category=`，优先用它（少传无用数据）；客户端的 `foliaIsWallpaperCategory`
+ * 是兜底，防服务端忽略参数或以后新增分类。
+ */
+const FOLIA_API_CATEGORY = 'wallpaper';
+/** 明确**不是**壁纸的分类。没列进来的（含未来新增的）一律放行 —— 宁可多显示，不静默丢。 */
+const FOLIA_NON_WALLPAPER_CATEGORIES = ['boot-animation', 'skin-pack', 'skin', 'pet', 'pets', 'assistant-skin'];
+/** 分页上限：防止站点游标异常时无限翻页（每页 12~24，20 页足够几百条）。 */
+/** 每次请求要多少条：接口支持 `?limit=`（实测 limit=5 生效），一次要 100 条能把
+ *  几百张图的清单压到个位数请求。 */
+const FOLIA_API_LIMIT = 100;
+/** 条目总数上限（防止站点数据异常时无限翻页）。100 × 20 = 2000 条。 */
+const FOLIA_API_MAX_PAGES = 20;
+const FOLIA_CATALOG_PATH = '/data/catalog.json';
+const FOLIA_MANIFEST_PATH = '/manifest.json';
 const FOLIA_TTL_MS = 60000;
 const FOLIA_TIMEOUT_DEFAULT_MS = 4000;
 const FOLIA_TIMEOUT_MIN_MS = 1000;
@@ -133,6 +168,110 @@ function foliaAbs(base, u) {
   return base + (s.startsWith('/') ? s : '/' + s);
 }
 
+/**
+ * 条目类型。优先级：**mime** > kind > URL 后缀。
+ *
+ * 站点目录的条目长这样：`{ slug, title, kind: 'dynamic', mime: 'video/mp4', url: '/media/...' }` ——
+ * 它没有 `file` 字段，而且 `kind: 'dynamic'` 既可能是视频也可能是有动画的图，所以 mime 最可靠。
+ */
+function foliaTypeOfEntry(it) {
+  const mime = String((it && it.mime) || '').toLowerCase();
+  if (mime.startsWith('video/')) return 'video';
+  if (mime.startsWith('image/')) return 'image';
+  const kind = String((it && it.kind) || '').toLowerCase();
+  if (kind === 'video' || kind === 'dynamic') return 'video';
+  if (kind === 'image') return 'image';
+  const probe = String((it && (it.file || it.url || it.slug)) || '');
+  if (/\.(mp4|webm|mov|m4v)$/i.test(probe)) return 'video';
+  if (/\.(jpg|jpeg|png|webp|gif|avif)$/i.test(probe)) return 'image';
+  return null;
+}
+
+/** 条目的分类 slug（没有就返回空串）。 */
+function foliaCategoryOf(it) {
+  const c = it && it.category;
+  return String((c && c.slug) || '').trim().toLowerCase();
+}
+
+/**
+ * 它是不是一条"壁纸"。黑名单制：只有明确属于其它模块的分类才排除。
+ * 不用白名单，是因为站点以后加分类时白名单会静默把新东西吞掉。
+ */
+function foliaIsWallpaperCategory(it) {
+  const slug = foliaCategoryOf(it);
+  if (!slug) return true;
+  return !FOLIA_NON_WALLPAPER_CATEGORIES.includes(slug);
+}
+
+/** 站点目录的一条 → inventory 条目。判不出类型/没有媒体地址就返回 null。 */
+function foliaItemFromCatalog(it, base) {
+  const type = foliaTypeOfEntry(it);
+  if (!type) return null;
+  const media = foliaAbs(base, it && it.url);
+  if (!media) return null;
+  const slug = String((it && (it.slug || it.id)) || '');
+  // 站点图片的预览走宿主缩略图代理：卡片只下 ~10 KB，不再下 500 KB 原图。
+  // （视频没有封面，保持 null —— 卡片会显示「无预览」，不会去拉整段视频。）
+  // 预览优先级：**站点自己给的 preview 最高**（省掉宿主这一跳，也最省流量）；
+  // 站点没给才退回宿主缩略图代理。只有预览走小图，`media` 永远是原图 ——
+  // 应用壁纸用的是 `media`，所以画质不受影响。
+  const sitePreview = foliaAbs(base, it && (it.preview || it.poster)) || null;
+  const thumb = sitePreview ? null : (type === 'image' ? '/folia/site-thumb?u=' + encodeURIComponent(media) : null);
+  const extHit = String(media).match(/\.([a-z0-9]{2,5})(?:[?#]|$)/i);
+  const num = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Number(v) : undefined);
+  return {
+    id: 'folia-' + (slug || media),
+    title: String((it && it.title) || slug || 'Folia'),
+    type,                                   // 'video' | 'image'
+    contentrating: null,
+    playable: true,
+    media,                                  // 绝对 URL
+    mediaExt: '.' + (extHit ? extHit[1].toLowerCase() : (type === 'video' ? 'mp4' : 'jpg')),
+    // 站点目录可能带 preview/poster；图片没封面时用自己当预览，视频没有就留空（卡片会是黑块）
+    preview: sitePreview || thumb || null,
+    frameUrl: null,
+    schemeColor: null,
+    sceneLiveSrc: null,
+    sceneVideo: null,
+    sceneAudio: null,
+    propsUrl: null,
+    liveFrame: null,
+    source: 'folia',
+    bytes: num(it && it.bytes),
+    width: num(it && it.width),
+    height: num(it && it.height),
+    durationMs: num(it && it.durationMs),
+  };
+}
+
+/** 旧静态清单 `{ images: [...] }` 的一条 → inventory 条目。 */
+function foliaItemFromManifest(it, base) {
+  const type = foliaTypeOfEntry(it);
+  if (!type) return null;
+  const file = String((it && (it.file || it.id)) || '');
+  const media = foliaAbs(base, it && it.url);
+  if (!media) return null;
+  const ext = (file.split('.').pop() || (type === 'video' ? 'mp4' : 'jpg')).toLowerCase();
+  return {
+    id: 'folia-' + (file || media),
+    title: String((it && it.title) || file || 'Folia'),
+    type,
+    contentrating: null,
+    playable: true,
+    media,
+    mediaExt: '.' + ext,
+    preview: foliaAbs(base, it && it.preview) || (type === 'image' ? media : null),
+    frameUrl: null,
+    schemeColor: null,
+    sceneLiveSrc: null,
+    sceneVideo: null,
+    sceneAudio: null,
+    propsUrl: null,
+    liveFrame: null,
+    source: 'folia',
+  };
+}
+
 /** 条目类型：先看 `kind`，回落到文件后缀。判不出返回 null（丢弃）。 */
 function foliaTypeOf(it) {
   const file = String(it && it.file ? it.file : '');
@@ -160,65 +299,92 @@ async function foliaRemote(force = false) {
   }
 
   const startedAt = Date.now();
-  const url = base + '/manifest.json';
   /** @type {any[]} */
   let items = [];
   let error = null;
+  let usedPath = FOLIA_CATALOG_PATH;
 
-  try {
+  /** 抓一个 JSON；返回 { doc, error }，永不抛。 */
+  const fetchJson = async (path) => {
     const signal = typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function'
       ? AbortSignal.timeout(foliaTimeoutMs())
       : undefined;
-    const res = await fetch(url, { headers: { accept: 'application/json' }, signal });
-    if (!res.ok) {
-      error = 'http-' + res.status;
-    } else {
-      let doc;
+    try {
+      const res = await fetch(base + path, { headers: { accept: 'application/json' }, signal });
+      if (!res.ok) return { doc: null, error: 'http-' + res.status };
       try {
-        doc = await res.json();
+        return { doc: await res.json(), error: null };
       } catch {
-        error = 'json';
-      }
-      if (doc) {
-        const list = Array.isArray(doc.images) ? doc.images : [];
-        for (const it of list) {
-          const type = foliaTypeOf(it);
-          if (!type) continue;
-          const file = String((it && (it.file || it.id)) || '');
-          const media = foliaAbs(base, it && it.url);
-          if (!media) continue;
-          const ext = (file.split('.').pop() || (type === 'video' ? 'mp4' : 'jpg')).toLowerCase();
-          items.push({
-            id: 'folia-' + (file || media),
-            title: String((it && it.title) || file || 'Folia'),
-            type,                                   // 'video' | 'image'
-            contentrating: null,
-            playable: true,
-            media,                                  // 绝对 URL
-            mediaExt: '.' + ext,
-            preview: foliaAbs(base, it && it.preview) || (type === 'image' ? media : null),
-            frameUrl: null,
-            schemeColor: null,
-            sceneLiveSrc: null,
-            sceneVideo: null,
-            sceneAudio: null,
-            propsUrl: null,
-            liveFrame: null,
-            source: 'folia',                        // 客户端可据此区分来源（未知字段会被忽略）
-          });
-        }
+        return { doc: null, error: 'json' };
       }
+    } catch (e) {
+      const code = String((e && (e.name || e.code)) || '');
+      const msg = String((e && e.message) || '');
+      if (/timeout|abort/i.test(code) || /timeout|aborted/i.test(msg)) return { doc: null, error: 'timeout' };
+      if (/cert|tls|ssl/i.test(msg)) return { doc: null, error: 'tls' };
+      return { doc: null, error: 'network' };
+    }
+  };
+
+  /**
+   * 拉接口的全部条目（按游标翻页）。任何一页失败就停，用已拿到的那些 ——
+   * 半份列表也比空列表有用。
+   */
+  const fetchApiItems = async () => {
+    const out = [];
+    let cursor = null;
+    for (let page = 0; page < FOLIA_API_MAX_PAGES; page++) {
+      const scope = '?category=' + encodeURIComponent(FOLIA_API_CATEGORY) + '&limit=' + FOLIA_API_LIMIT;
+      const qs = cursor ? FOLIA_API_PATH + scope + '&cursor=' + encodeURIComponent(cursor) : FOLIA_API_PATH + scope;
+      const { doc, error } = await fetchJson(qs);
+      if (!doc || !doc.ok || !doc.data) return { items: out, error: error || 'api-shape' };
+      const items = Array.isArray(doc.data.items) ? doc.data.items : [];
+      out.push(...items);
+      if (!doc.data.hasMore || !doc.data.nextCursor) return { items: out, error: null };
+      cursor = doc.data.nextCursor;
     }
-  } catch (e) {
-    const code = String((e && (e.name || e.code)) || '');
-    const msg = String((e && e.message) || '');
-    if (/timeout|abort/i.test(code) || /timeout|aborted/i.test(msg)) error = 'timeout';
-    else if (/cert|tls|ssl/i.test(msg)) error = 'tls';
-    else error = 'network';
+    return { items: out, error: null };
+  };
+
+  // ① 站点**接口**（真源）：`{ ok, data: { items: [...] } }`
+  const api = await fetchApiItems();
+  if (api.items.length) {
+    for (const it of api.items) {
+      if (!foliaIsWallpaperCategory(it)) continue;   // 兜底：服务端过滤失效时也不把开机动画当壁纸
+      const one = foliaItemFromCatalog(it, base);
+      if (one) items.push(one);
+    }
+    usedPath = FOLIA_API_PATH + '?category=' + FOLIA_API_CATEGORY;
   }
 
+  // ② 站点目录（静态快照）：`{ wallpapers: [{ slug, mime, url, ... }] }`
+  if (items.length === 0) {
+  const cat = await fetchJson(FOLIA_CATALOG_PATH);
+  if (cat.doc && Array.isArray(cat.doc.wallpapers)) {
+    for (const it of cat.doc.wallpapers) {
+      if (!foliaIsWallpaperCategory(it)) continue;   // 快照里也混着开机动画，同样按分类排掉
+      const one = foliaItemFromCatalog(it, base);
+      if (one) items.push(one);
+    }
+    if (items.length === 0) error = 'empty';
+  } else {
+    // ② 回退到旧静态清单：`{ images: [{ file, url, ... }] }`
+    usedPath = FOLIA_MANIFEST_PATH;
+    const man = await fetchJson(FOLIA_MANIFEST_PATH);
+    if (man.doc && Array.isArray(man.doc.images)) {
+      for (const it of man.doc.images) {
+        const one = foliaItemFromManifest(it, base);
+        if (one) items.push(one);
+      }
+      if (items.length === 0) error = 'empty';
+    } else {
+      // 两条都不成立：报 catalog 的错（它是真源，错因更有诊断价值）
+      error = cat.error || man.error || 'network';
+    }
+  }
+  }
   const status = {
-    url,
+    url: base + usedPath,
     ok: error === null,
     count: items.length,
     ms: Date.now() - startedAt,

package/lib/routes/modules.js

@@ -0,0 +1,186 @@
+/**
+ * routes/modules.js — 数据模块索引（站点侧声明"有哪些数据模块"）。
+ *
+ * 为什么需要它：插件的能力是固定的（壁纸库、开机动画…），但**站点会一直加新东西**。
+ * 把"有哪些模块、每个模块的清单在哪、该用哪个 handler 处理"放进一份索引里，插件就不必
+ * 为每加一批素材发一次版 —— 它读索引，按 handler 决定自己认不认识。
+ *
+ * 解析顺序（**站点优先，R2 兜底，内置最后**）：
+ *
+ *   ① `<site>/data/modules.json`       站点自己维护的索引（你以后放进 Pages 即优先）
+ *   ② `<assets>/data/modules.json`     R2 桶上的索引（当前由我们维护）
+ *   ③ 内置默认                          两条都读不到时的最小集合
+ *
+ * 页面/助手只调 `/folia/modules` 这一个入口，具体从哪来的写在 `source` 里 —— 排查时
+ * 不用猜"到底读的哪份"。
+ */
+import { sendJson } from '../json-response.js';
+
+/** 站点基址（与 inventory 同一套环境变量，保持"换站只改一处"的手感）。 */
+const DEFAULT_SITE = 'https://folia-5ve.pages.dev';
+/** 素材桶基址：托管 <site> 上暂时没有的模块清单（例如 boot 素材）。 */
+const DEFAULT_ASSETS = 'https://pub-1275321f146e479eaac54948f4cdad6f.r2.dev';
+
+/**
+ * 索引可能落在哪。**按顺序试**，第一个返回 JSON 的胜出：
+ *
+ *   /data/modules.json        站点自己的静态路径（你以后把文件放进 Pages 时用这条）
+ *   /media/data/modules.json  站点的 /media 代理 —— 它把 /media/X 映射到 R2 的键 X，
+ *                             所以这条能读到 R2 上的 data/modules.json（现在走这条）
+ *
+ * 为什么重要：站点的 /data/* 没有 Function，未知路径会回退 index.html；
+ * 而 /media/* 有代理。走 /media/ 让"全部数据都从站点域名来"成立，R2 只是背后的仓库。
+ */
+const MODULES_PATHS = ['/data/modules.json', '/media/data/modules.json'];
+const TTL_MS = 60000;
+const TIMEOUT_MS = 8000;
+
+function siteBase() {
+  const raw = process.env.DSH_FOLIA_SITE;
+  if (typeof raw === 'string' && raw.trim().toLowerCase() === 'off') return null;
+  const base = (typeof raw === 'string' && raw.trim()) ? raw.trim() : DEFAULT_SITE;
+  return base.replace(/\/+$/, '');
+}
+
+function assetsBase() {
+  const raw = process.env.DSH_FOLIA_ASSETS;
+  const base = (typeof raw === 'string' && raw.trim()) ? raw.trim() : DEFAULT_ASSETS;
+  return base.replace(/\/+$/, '');
+}
+
+/**
+ * 内置默认索引。**只在两条网络源都不可用时使用** —— 它同时也是一份"契约示例"：
+ * 想加模块时照这个形状写，不必读代码。
+ */
+const BUILTIN = {
+  version: 1,
+  modules: [
+    {
+      id: 'wallpapers',
+      name: '壁纸',
+      handler: 'wallpaper-library',
+      status: 'live',
+      manifest: '/data/catalog.json',
+      fallbackManifest: '/manifest.json',
+    },
+    {
+      id: 'boot',
+      name: '开机动画',
+      handler: 'boot-animation',
+      status: 'planned',
+      manifest: '/boot/manifest.json',
+    },
+  ],
+};
+
+/** @type {{ at: number, payload: any | null }} */
+let cache = { at: 0, payload: null };
+
+/** 形状校验：宁可判为无效（回落下一层），也不把半截数据当索引下发。 */
+function normalize(doc, origin) {
+  if (!doc || typeof doc !== 'object') return null;
+  const list = Array.isArray(doc.modules) ? doc.modules : null;
+  if (!list) return null;
+  const modules = [];
+  for (const m of list) {
+    if (!m || typeof m !== 'object') continue;
+    const id = String(m.id || '').trim();
+    const handler = String(m.handler || '').trim();
+    if (!id || !handler) continue;       // 没有 id 或 handler 的条目无法被使用
+    modules.push({
+      id,
+      name: String(m.name || id),
+      handler,
+      status: String(m.status || 'live'),
+      manifest: m.manifest ? String(m.manifest) : null,
+      fallbackManifest: m.fallbackManifest ? String(m.fallbackManifest) : null,
+      description: m.description ? String(m.description) : null,
+      requirements: m.requirements && typeof m.requirements === 'object' ? m.requirements : null,
+    });
+  }
+  return { version: doc.version || 1, updatedAt: doc.updatedAt || null, origin, modules };
+}
+
+async function fetchJson(url) {
+  // 网络抖动（境外 CDN 偶发 connect timeout）不该让索引退回内置集合 —— 重试一次。
+  // 只对 network/timeout 重试；`not-json` / `http-4xx` 是确定性结果，重试没意义。
+  let lastError = 'network';
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const res = await fetch(url, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      });
+      if (!res.ok) return { doc: null, error: 'http-' + res.status };
+      const ct = String(res.headers.get('content-type') || '');
+      // 站点把未知路径回落到 index.html，这里必须挡住：HTML 不是索引。
+      if (ct && !/json/i.test(ct)) return { doc: null, error: 'not-json' };
+      return { doc: await res.json(), error: null };
+    } catch (e) {
+      const msg = String((e && e.message) || '');
+      lastError = /timeout|abort/i.test(msg) ? 'timeout' : 'network';
+      if (attempt === 0) await new Promise((r) => setTimeout(r, 600));
+    }
+  }
+  return { doc: null, error: lastError };
+}
+
+/**
+ * 解析模块索引。永不抛 —— 索引只是"能多发现一点东西"，读不到就必须退回内置集合，
+ * 绝不能让面板因为一个索引文件而空白。
+ */
+export async function resolveModules(force = false) {
+  if (!force && Date.now() - cache.at < TTL_MS && cache.payload) return cache.payload;
+
+  const tried = [];
+  const site = siteBase();
+  const assets = assetsBase();
+
+  // 站点先试（它优先），每个基址再按路径表试；R2 直接地址留作最后兜底。
+  const bases = [
+    ...(site ? [{ base: site, origin: 'site' }] : []),
+    { base: assets, origin: 'assets' },
+  ];
+  for (const { base, origin } of bases) {
+    for (const path of MODULES_PATHS) {
+    const url = base + path;
+    const { doc, error } = await fetchJson(url);
+    tried.push({ url, error });
+    if (doc) {
+      const norm = normalize(doc, origin);
+      if (norm) {
+        // 相对清单路径补成绝对 URL：调用方不必再关心基址是谁。
+        for (const m of norm.modules) {
+          if (m.manifest && m.manifest.startsWith('/')) m.manifest = base + m.manifest;
+          if (m.fallbackManifest && m.fallbackManifest.startsWith('/')) m.fallbackManifest = base + m.fallbackManifest;
+        }
+        const payload = { ok: true, source: norm.origin, url, updatedAt: norm.updatedAt, modules: norm.modules, tried };
+        cache = { at: Date.now(), payload };
+        return payload;
+      }
+      tried[tried.length - 1].error = 'bad-shape';
+    }
+    }
+  }
+
+  const payload = { ok: false, source: 'builtin', url: null, updatedAt: null, modules: BUILTIN.modules, tried };
+  cache = { at: Date.now(), payload };
+  return payload;
+}
+
+export function registerModulesRoutes(webServer, c) {
+  const { disposers, base: BASE } = c;
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/modules`,
+    handler: async (req, res) => {
+      let force = false;
+      try {
+        force = new URL(req.url || '/', 'http://x').searchParams.get('refresh') === '1';
+      } catch { /* 解析失败就当没传 */ }
+      const payload = await resolveModules(force);
+      sendJson(res, 200, payload);
+    },
+  }));
+}

package/lib/routes/site-thumb.js

@@ -0,0 +1,109 @@
+/**
+ * routes/site-thumb.js — 站点图片的**缩略图代理**。
+ *
+ * 为什么需要它：站点上的壁纸是 1024×1024 起的原图（实测一张 536 KB）。卡片网格一页
+ * 9~12 张，一次要下 5 MB 左右，在慢网络上就是"站点壁纸加载很慢"。
+ *
+ * 做法：宿主把原图抓一次存到缓存，然后用**已有的** `ensureImagePreview`（ffmpeg 缩到
+ * 320px、q=5，约 10 KB）生成小图，之后每次都直接发小图。原图只下一次、只在第一次。
+ *
+ * 三条纪律：
+ *   · **只代理白名单主机**（站点基址与素材桶），避免变成任意 URL 的开放代理；
+ *   · 任何失败都 **302 回原图** —— 慢一点但一定能显示，绝不 404；
+ *   · 缩略图与源图都按 URL 的 sha1 命名，天然幂等，不需要失效逻辑。
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream, existsSync, mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { extname, join } from 'node:path';
+
+const MAX_SOURCE_BYTES = 32 * 1024 * 1024;
+const FETCH_TIMEOUT_MS = 30000;
+
+const DEFAULT_SITE = 'https://folia-5ve.pages.dev';
+const DEFAULT_ASSETS = 'https://pub-1275321f146e479eaac54948f4cdad6f.r2.dev';
+
+function siteBase() {
+  const raw = process.env.DSH_FOLIA_SITE;
+  if (typeof raw === 'string' && raw.trim().toLowerCase() === 'off') return null;
+  const base = (typeof raw === 'string' && raw.trim()) ? raw.trim() : DEFAULT_SITE;
+  return base.replace(/\/+$/, '');
+}
+function assetsBase() {
+  const raw = process.env.DSH_FOLIA_ASSETS;
+  const base = (typeof raw === 'string' && raw.trim()) ? raw.trim() : DEFAULT_ASSETS;
+  return base.replace(/\/+$/, '');
+}
+
+/** 源图缓存目录（与 config.json 同一个数据根）。 */
+function sourceDir() {
+  const base = process.env.DSH_FOLIA_HOME || join(homedir(), '.dsh-folia');
+  const d = join(base, 'site-src');
+  try { if (!existsSync(d)) mkdirSync(d, { recursive: true }); } catch { /* 只读盘：后面会失败并回退 */ }
+  return d;
+}
+
+/** 只允许抓我们自己的两个主机。 */
+function allowed(url) {
+  try {
+    const u = new URL(url);
+    if (!/^https?:$/.test(u.protocol)) return false;
+    const hosts = [siteBase(), assetsBase()].filter(Boolean).map((b) => { try { return new URL(b).host; } catch { return ''; } });
+    return hosts.includes(u.host);
+  } catch {
+    return false;
+  }
+}
+
+export function registerSiteThumbRoutes(webServer, c) {
+  const { disposers, base: BASE, ensureImagePreview, log } = c;
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/site-thumb`,
+    handler: async (req, res) => {
+      let target = '';
+      try { target = new URL(req.url || '/', 'http://x').searchParams.get('u') || ''; } catch { target = ''; }
+
+      const redirect = () => {
+        res.statusCode = 302;
+        if (typeof res.setHeader === 'function') res.setHeader('location', target);
+        res.end();
+      };
+
+      if (!target || !allowed(target)) { redirect(); return; }
+
+      const key = createHash('sha1').update(target).digest('hex');
+      let ext = '.jpg';
+      try { ext = extname(new URL(target).pathname) || '.jpg'; } catch { /* 用默认 */ }
+      const src = join(sourceDir(), key + (ext.length <= 5 ? ext : '.jpg'));
+
+      try {
+        if (!existsSync(src) || statSync(src).size === 0) {
+          const r = await fetch(target, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+          if (!r.ok) { redirect(); return; }
+          const ct = String(r.headers.get('content-type') || '');
+          if (!/^image\//i.test(ct)) { redirect(); return; }
+          const buf = Buffer.from(await r.arrayBuffer());
+          if (buf.length === 0 || buf.length > MAX_SOURCE_BYTES) { redirect(); return; }
+          writeFileSync(src, buf);
+        }
+        // 已有套件：缩到 320px（失败返回 null ⇒ 回落原图）
+        const thumb = await ensureImagePreview(src).catch(() => null);
+        const file = thumb && existsSync(thumb) ? thumb : src;
+        const size = statSync(file).size;
+        if (typeof res.setHeader === 'function') {
+          res.setHeader('content-type', 'image/jpeg');
+          res.setHeader('content-length', String(size));
+          res.setHeader('cache-control', 'public, max-age=31536000, immutable');
+        }
+        res.statusCode = 200;
+        createReadStream(file).pipe(res);
+      } catch (e) {
+        if (typeof log === 'function') log(`[site-thumb] ${String((e && e.message) || e)}`);
+        try { if (existsSync(src)) rmSync(src); } catch { /* ignore */ }
+        redirect();
+      }
+    },
+  }));
+}

package/lib/settings-schema.js

@@ -596,6 +596,8 @@ const DEFAULTS = {
   contentRatingFilter: "everyone",
   // Wallpaper-type filter (all / video / web / image / scene). "all" disables it.
   typeFilter: "all",
+  // 壁纸来源：all / local（本机 Wallpaper Engine 库 + 上传）/ site（我们站点）
+  sourceFilter: "all",
   // Thumbnail-card style: "classic" (WE's original aspect-ratio 16/9 cards —
   // the CD-like look the author liked; can overlap in older browsers) or
   // "fixed" (fixed-height cards that never overlap). The vinyl
@@ -1040,6 +1042,7 @@ const KINDS = {
   objectFit: { kind: 'enum', values: OBJECT_FIT_VALUES },
   contentRatingFilter: { kind: 'enum', values: RATING_VALUES },
   typeFilter: { kind: 'enum', values: TYPE_VALUES },
+  sourceFilter: { kind: 'enum', values: ['all', 'local', 'site'] },
   pickerLayout: { kind: 'enum', values: PICKER_LAYOUT_VALUES },
   edgeCompat: { kind: 'boolTrue' },
   accent: { kind: 'hex' },
@@ -1291,7 +1294,7 @@ const RESET_TABS = {
   library: [
     'switchTransition', 'switchTransitionDir', 'switchTransitionSpeed',
     'rotationEnabled', 'rotationGroupId', 'rotationGroups', 'rotationSeeded',
-    'contentRatingFilter', 'typeFilter', 'pickerLayout',
+    'contentRatingFilter', 'typeFilter', 'sourceFilter', 'pickerLayout',
   ],
   // 外观：玻璃 / 侧栏与四角 / 标题栏 / 思考块 / 浮层 / 主题预设 / 字体 / UI 配色。
   appearance: [
@@ -1926,7 +1929,7 @@ const SETTINGS_NAMESPACES = {
     'id', 'hiddenIds', 'rotationEnabled', 'rotationGroupId', 'rotationGroups', 'rotationSeeded',
     'playbackRate', 'videoVolume', 'videoAudioEnabled', 'fpsCap', 'sceneLive', 'sceneLiveFps',
     'liveBootDelay', 'sceneLiveFailures', 'pauseOnHidden', 'pauseOnBlur', 'pauseOnBattery',
-    'flip', 'objectFit', 'contentRatingFilter', 'typeFilter', 'pickerLayout', 'edgeCompat',
+    'flip', 'objectFit', 'contentRatingFilter', 'typeFilter', 'sourceFilter', 'pickerLayout', 'edgeCompat',
     'userProps', 'noticeSeen', 'layerPositionX', 'layerPositionY', 'layerScale',
   ],
   // 玻璃 / 材质 / 侧栏 / 过渡（`accent`、`glassMode` 与皮肤让路之外的整套玻璃登记表都在这里）

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-folia",
-    "version":  "3.9.1",
+    "version":  "4.0.0",
     "description":  "Folia 壁纸引擎：把本机 Wallpaper Engine 壁纸搬进 DSH 界面（场景实时渲染 / 视频 / 网页），内置液态玻璃与 Folia 吉祥物，并可从自建站点拉取壁纸。单包形态（组件已合并）。",
     "type":  "module",
     "engines":  {
@@ -50,6 +50,7 @@
                   "lib/kernel/config.js",
                   "lib/kernel/host-kernel.js",
                   "lib/kernel/host-session.js",
+                  "lib/boot/",
                   "lib/routes/",
                   "lib/occlusion/",
                   "lib/fontsets/",
@@ -188,7 +189,9 @@
                     "verify:static":  "node test/verify-static.mjs",
                     "smoke":  "node test/run-guards.mjs smoke",
                     "verify:all":  "node test/run-guards.mjs all",
-                    "prepack":  "node scripts/prepare.mjs"
+                    "prepack":  "node scripts/prepare.mjs",
+                    "test:boot":  "node test/boot-http.mjs",
+                    "gate":  "node scripts/build-client.mjs \u0026\u0026 node test/run-guards.mjs smoke \u0026\u0026 node test/boot-http.mjs"
                 },
     "peerDependencies":  {
                              "@deepseek-ai/cordis":  "^4.0.4",
@@ -209,7 +212,6 @@
                                                                      }
                              },
     "dependencies":  {
-                         "@linxin666/dsh-client-ui-skin-center":  "^0.4.8",
                          "webwallgl":  "^3.0.0",
                          "x11":  "^4.3.1"
                      },