dsh-folia 2.5.1 → 2.5.8

package/lib/index.js

@@ -78,6 +78,10 @@ import { assertSubpackagesResolvable, assertSubpackagesResolvableInHost, httpVie
 import { createHostSession } from './kernel/host-session.js';
 export { extOf };
 import { registerInventoryRoutes } from './routes/inventory.js';
+import { registerModulesRoutes } from './routes/modules.js';
+import { registerBootRoutes } from './routes/boot.js';
+import { registerSiteThumbRoutes } from './routes/site-thumb.js';
+import { installBootInjection } from './boot/index.js';
 import { registerDiagRoutes } from './routes/diag.js';
 // 遮挡消息桥族（上游新增域模块）：hub 处理 x11 遮挡探针，路由对外暴露状态/控制面。
 import { createOcclusionHub } from './occlusion/index.js';
@@ -94,7 +98,6 @@ import { registerPropsRoutes } from './routes/props.js';
 import { registerLiveFrameRoutes } from './routes/live-frame.js';
 import { registerSettingsRoutes } from './routes/settings.js';
 import { registerCacheDirRoutes } from './routes/cache-dir.js';
-import { registerSkinRoutes } from './routes/skins.js';
 // C8′/C6 出户的组件行（P2-1 / P2-2）：组件入口**静态** import（不是动态）—— `test/verify-reachability.mjs`
 // 只从 ENTRY 沿 import 边走，动态加载的组件入口会被判定为不可达，棘轮当场变红。
 // 组件名 → 实现表的登记在 `applyComponent` **函数体内**（P2-1b 起；模块级常量会让门面求值期
@@ -294,6 +297,17 @@ export function apply(ctx) {
   registerInventoryRoutes(webServer, {
     disposers, base: BASE, mediaOriginApi, buildInventory, componentsProbe: componentProbe,
   });
+  // 数据模块索引（站点侧声明「有哪些数据模块」）→ 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 });
+  installBootInjection(ctx, (m) => { try { log(m); } catch { /* ignore */ } });
 
   // 3./3a. 派生媒体族路由（源元信息 / 抽帧转码 + 进度 / 视频缩略图）→ lib/routes/media-derived.js。
   //        四条注册与它们的依赖都在那个文件里；这里只声明它的依赖。**调用点必须早于下面的
@@ -496,14 +510,6 @@ export function apply(ctx) {
     normalizeUserDir, cacheBaseDir, setCacheDir, armBodyIdleTimeout,
   });
 
-  // 7c. 「皮肤包」数据源（自建站）→ lib/routes/skins.js。一条 prefix 注册带五个动作
-  //     （索引 / 安装 / 激活 / 卸载 / 预览图代理）。
-  //     ⚠️ 渲染不在这里：落到 `harness/skins/<id>/` 之后，应用样式与 hooks 的仍是
-  //     皮肤中心（dsh-skin-center）。本族只负责"取、验、落、切"。
-  registerSkinRoutes(webServer, {
-    disposers, base: BASE, log,
-  });
-
   // fiber disposer 的语义（先逐个 disposer、再 releaseKernelLease(hostKernel)——内核引用计数
   // 归零才 `transcodeKit.dispose()`——再 destroy 在途流、清 activeStreams / mediaMap）
   // 逐字搬进 lib/kernel/host-session.js 的 `dispose()`。

package/lib/routes/boot.js

@@ -0,0 +1,325 @@
+/**
+ * routes/boot.js — 开机动画的 HTTP 面：列候选 / 下载 / 选择 / 删除 / 流式播放。
+ *
+ * 数据来自两处：
+ *   · **候选清单** = 模块索引里的 `boot` 模块（`manifest` 指向一份 `{ clips: [...] }`），
+ *     站点优先、R2 兜底 —— 复用 `routes/modules.js` 的解析，不另造一套基址。
+ *   · **本地文件** = `~/.dsh-folia/boot/<id>.mp4`，由「下载」写进来。
+ *
+ * 播放走 `/folia/boot/clip`，**支持 Range**：注入的 `<video>` 与浏览器都靠它边下边播。
+ * 这也是为什么片段必须先落盘 —— 启动路径上不能有网络。
+ */
+import { createReadStream, existsSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sendJson } from '../json-response.js';
+import { bodyReader } from '../http-body.js';
+import { resolveModules } from './modules.js';
+import { bootDir, clipExists, clipFile, listLocalClips, readBoot, removeClip, writeBoot } from '../boot/index.js';
+
+/**
+ * 站点基址。开机动画的候选**从站点分类取**（`?category=boot-animation`），
+ * 与壁纸页签用的是同一个接口 —— 站点上看到 3 条，这里就是 3 条，不会各说各话。
+ */
+const DEFAULT_SITE = 'https://folia-5ve.pages.dev';
+const BOOT_CATEGORY = 'boot-animation';
+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(/\/+$/, '');
+}
+
+const CLIP_MAX_BYTES = 64 * 1024 * 1024;
+const FETCH_TIMEOUT_MS = 60000;
+
+/**
+ * 读完一个小 JSON 请求体。
+ *
+ * ⚠️ `bodyReader()` 是**流式**收体器（返回 `{ onData, text() }`），不是 Promise ——
+ *    必须自己把 `req` 的 data/end 挂上去。把它 `await` 出来会拿到那个对象，
+ *    `JSON.parse` 立刻抛、被 catch 成 null，于是每个写操作都报 `bad-id`。
+ */
+function readBodyText(req, maxBytes) {
+  return new Promise((resolve) => {
+    let tooLarge = false;
+    const reader = bodyReader(req, { maxBytes, onOverflow: () => { tooLarge = true; } });
+    const finish = () => resolve(tooLarge ? '' : reader.text());
+    try {
+      req.on('data', reader.onData);
+      req.on('end', finish);
+      req.on('error', () => resolve(''));
+    } catch {
+      resolve('');
+    }
+  });
+}
+
+/** 读请求体里的 `{ id }`。 */
+async function readIdBody(req) {
+  try {
+    const text = await readBodyText(req, 64 * 1024);
+    const doc = JSON.parse(text || '{}');
+    const id = String((doc && doc.id) || '').trim();
+    return /^[a-z0-9][a-z0-9._-]*$/i.test(id) ? id : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 候选清单：模块索引里的 `boot` 模块 → 拉它的 manifest → `{ clips: [...] }`。
+ * 失败一律返回空数组（面板显示"没有候选"），绝不抛。
+ */
+async function fetchCandidates() {
+  // ① 站点分类接口（与壁纸同一个接口，只是 category 不同）
+  const site = siteBase();
+  if (site) {
+    try {
+      const res = await fetch(site + '/api/public/wallpapers?category=' + BOOT_CATEGORY, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(15000),
+      });
+      if (res.ok) {
+        const doc = await res.json();
+        const items = (doc && doc.data && Array.isArray(doc.data.items)) ? doc.data.items : [];
+        const clips = items.map((it) => ({
+          id: String((it && (it.slug || it.id)) || ''),
+          title: String((it && it.title) || (it && it.slug) || ''),
+          // 站点接口给的是相对路径（/media/...），下载时要绝对地址 —— 这里补上，
+          // 否则 fetch 一个相对路径会当场失败。
+          url: (() => { const u = String((it && it.url) || ''); return /^https?:/i.test(u) ? u : (u ? site + u : ''); })(),
+          bytes: Number(it && it.bytes) || null,
+          sha256: it && it.sha256 ? String(it.sha256) : null,
+          durationSec: it && it.durationMs ? Number(it.durationMs) / 1000 : null,
+          faststart: true,
+        })).filter((c) => c.id && c.url);
+        if (clips.length) return { clips, error: null };
+      }
+    } catch { /* 落到模块清单 */ }
+  }
+
+  // ② 模块索引里的 boot 清单（站点不可达时的兜底）
+  try {
+    const index = await resolveModules(false);
+    const mod = (index.modules || []).find((m) => m.id === 'boot');
+    if (!mod || !mod.manifest || mod.status === 'disabled') return { clips: [], error: 'no-module' };
+    const res = await fetch(mod.manifest, {
+      headers: { accept: 'application/json' },
+      signal: AbortSignal.timeout(15000),
+    });
+    if (!res.ok) return { clips: [], error: 'http-' + res.status };
+    const doc = await res.json();
+    const list = Array.isArray(doc && doc.clips) ? doc.clips : [];
+    const base = mod.manifest.replace(/\/[^/]*$/, '');
+    const clips = list.map((c) => {
+      const file = String((c && (c.file || c.id)) || '');
+      const url = c && c.url ? String(c.url) : (base + '/' + file);
+      return {
+        id: String((c && c.id) || file.replace(/\.mp4$/i, '')),
+        title: String((c && (c.name || c.title)) || c.id || file),
+        url,
+        bytes: Number(c && c.bytes) || null,
+        sha256: c && c.sha256 ? String(c.sha256) : null,
+        durationSec: Number(c && c.durationSec) || null,
+        faststart: c && c.faststart === true,
+      };
+    }).filter((c) => c.id && c.url);
+    return { clips, error: null };
+  } catch (e) {
+    return { clips: [], error: 'network' };
+  }
+}
+
+export function registerBootRoutes(webServer, c) {
+  const { disposers, base: BASE, log } = c;
+
+  /* ① 候选 + 本地状态（面板一次拿全） */
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/boot/list`,
+    handler: async (req, res) => {
+      let force = false;
+      try { force = new URL(req.url || '/', 'http://x').searchParams.get('refresh') === '1'; } catch { /* ignore */ }
+      if (force) await resolveModules(true);
+      const [boot, candidates] = await Promise.all([Promise.resolve(readBoot()), fetchCandidates()]);
+      const local = listLocalClips();
+      const localById = new Map(local.map((x) => [x.id, x]));
+      const clips = candidates.clips.map((c) => {
+        const have = localById.get(c.id) || null;
+        return { ...c, installed: Boolean(have), localBytes: have ? have.bytes : null };
+      });
+      // 本地有、清单里没有的（我们换了站点/清单）：也列出来，否则用户删不掉。
+      const known = new Set(clips.map((c) => c.id));
+      for (const it of local) {
+        if (known.has(it.id)) continue;
+        clips.push({
+          id: it.id, title: it.title, url: null, bytes: null, sha256: null,
+          durationSec: it.durationSec, faststart: true,
+          installed: true, localBytes: it.bytes, orphan: true,
+        });
+      }
+      sendJson(res, 200, {
+        ok: true,
+        enabled: boot.enabled,
+        clipId: boot.clipId,
+        enterMode: boot.enterMode,
+        fadeMs: boot.fadeMs,
+        minShowMs: boot.minShowMs,
+        maxHoldMs: boot.maxHoldMs,
+        sound: boot.sound,
+        clips,
+        error: candidates.error,
+      });
+    },
+  }));
+
+  /* ② 下载一条到本地 */
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/boot/download`,
+    handler: async (req, res) => {
+      const id = await readIdBody(req);
+      if (!id) { sendJson(res, 400, { ok: false, error: 'bad-id' }); return; }
+      const { clips } = await fetchCandidates();
+      const item = clips.find((c) => c.id === id);
+      if (!item) { sendJson(res, 404, { ok: false, error: 'not-in-catalog' }); return; }
+      const dest = clipFile(id);
+      if (!dest) { sendJson(res, 400, { ok: false, error: 'bad-id' }); return; }
+      try {
+        const r = await fetch(item.url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+        if (!r.ok) { sendJson(res, 502, { ok: false, error: 'http-' + r.status }); return; }
+        const ct = String(r.headers.get('content-type') || '');
+        const buf = Buffer.from(await r.arrayBuffer());
+        // 站点把未知路径回落到 HTML —— 这类"伪 200"绝不能当成视频存下来（否则每次开机黑屏）。
+        if (!/video\//i.test(ct) || buf.length < 1024 || buf.toString('latin1', 4, 8) !== 'ftyp') {
+          sendJson(res, 422, { ok: false, error: 'not-a-video', detail: ct || 'no content-type' });
+          return;
+        }
+        if (buf.length > CLIP_MAX_BYTES) { sendJson(res, 413, { ok: false, error: 'too-large' }); return; }
+        writeFileSync(dest, buf);
+        try {
+          writeFileSync(join(bootDir(), id + '.json'), JSON.stringify({
+            title: item.title, durationSec: item.durationSec, bytes: buf.length, sha256: item.sha256 || null,
+          }, null, 2) + '\n');
+        } catch { /* meta 只是锦上添花 */ }
+        if (typeof log === 'function') log(`[boot] downloaded ${id} (${(buf.length / 1048576).toFixed(1)} MB)`);
+        sendJson(res, 200, { ok: true, id, bytes: buf.length });
+      } catch (e) {
+        sendJson(res, 500, { ok: false, error: 'fetch-failed', detail: String((e && e.message) || e) });
+      }
+    },
+  }));
+
+  /* ③ 选择（并顺手启用） */
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/boot/select`,
+    handler: async (req, res) => {
+      const id = await readIdBody(req);
+      if (!id) { sendJson(res, 400, { ok: false, error: 'bad-id' }); return; }
+      if (!clipExists(id)) { sendJson(res, 404, { ok: false, error: 'not-installed' }); return; }
+      const boot = writeBoot({ clipId: id, enabled: true });
+      if (typeof log === 'function') log(`[boot] selected ${id}`);
+      sendJson(res, 200, { ok: true, ...boot });
+    },
+  }));
+
+  /* ④ 开关 */
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/boot/toggle`,
+    handler: async (req, res) => {
+      let enabled = false;
+      try {
+        const text = await readBodyText(req, 8 * 1024);
+        const doc = JSON.parse(text || '{}');
+        enabled = Boolean(doc && doc.enabled);
+      } catch { /* 坏请求当 false */ }
+      const boot = writeBoot({ enabled });
+      sendJson(res, 200, { ok: true, ...boot });
+    },
+  }));
+
+  /* ⑤ 设置（淡出 / 最短显示 / 最长停留） */
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/boot/settings`,
+    handler: async (req, res) => {
+      let patch = {};
+      try {
+        const text = await readBodyText(req, 8 * 1024);
+        const doc = JSON.parse(text || '{}');
+        if (doc && typeof doc === 'object') patch = doc;
+      } catch { /* 坏请求 = 不改 */ }
+      const boot = writeBoot({
+        ...(patch.enterMode !== undefined ? { enterMode: String(patch.enterMode) } : {}),
+        ...(patch.fadeMs !== undefined ? { fadeMs: Number(patch.fadeMs) } : {}),
+        ...(patch.minShowMs !== undefined ? { minShowMs: Number(patch.minShowMs) } : {}),
+        ...(patch.maxHoldMs !== undefined ? { maxHoldMs: Number(patch.maxHoldMs) } : {}),
+      });
+      sendJson(res, 200, { ok: true, ...boot });
+    },
+  }));
+
+  /* ⑥ 删除本地片段 */
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/boot/remove`,
+    handler: async (req, res) => {
+      const id = await readIdBody(req);
+      if (!id) { sendJson(res, 400, { ok: false, error: 'bad-id' }); return; }
+      const boot = readBoot();
+      if (boot.clipId === id) writeBoot({ clipId: '', enabled: false });
+      const ok = removeClip(id);
+      sendJson(res, 200, { ok, id });
+    },
+  }));
+
+  /* ⑦ 流式播放（Range） */
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/boot/clip`,
+    handler: async (req, res) => {
+      const boot = readBoot();
+      const id = boot.clipId;
+      const file = clipFile(id);
+      if (!file || !existsSync(file)) { res.statusCode = 404; res.end('no clip'); return; }
+      const size = statSync(file).size;
+      const range = String((req.headers && req.headers.range) || '');
+      const type = 'video/mp4';
+      // Range：`bytes=start-end` —— Chromium 播放本地大文件时会先发一小段探测请求。
+      const m = /^bytes=(\d*)-(\d*)$/.exec(range.trim());
+      if (m) {
+        let start = m[1] === '' ? null : Number(m[1]);
+        let end = m[2] === '' ? null : Number(m[2]);
+        if (start === null && end !== null) { start = Math.max(0, size - end); end = size - 1; }
+        if (start === null) start = 0;
+        if (end === null || end >= size) end = size - 1;
+        if (start > end || start >= size) {
+          res.statusCode = 416;
+          if (typeof res.setHeader === 'function') res.setHeader('content-range', `bytes */${size}`);
+          res.end();
+          return;
+        }
+        if (typeof res.setHeader === 'function') {
+          res.setHeader('content-type', type);
+          res.setHeader('content-length', String(end - start + 1));
+          res.setHeader('content-range', `bytes ${start}-${end}/${size}`);
+          res.setHeader('accept-ranges', 'bytes');
+          res.setHeader('cache-control', 'no-store');
+        }
+        res.statusCode = 206;
+        createReadStream(file, { start, end }).pipe(res);
+        return;
+      }
+      if (typeof res.setHeader === 'function') {
+        res.setHeader('content-type', type);
+        res.setHeader('content-length', String(size));
+        res.setHeader('accept-ranges', 'bytes');
+        res.setHeader('cache-control', 'no-store');
+      }
+      res.statusCode = 200;
+      createReadStream(file).pipe(res);
+    },
+  }));
+}

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,35 @@ 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 页足够几百条）。 */
+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 +164,106 @@ 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 —— 卡片会显示「无预览」，不会去拉整段视频。）
+  const thumb = 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: thumb || foliaAbs(base, it && (it.preview || it.poster)) || 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 +291,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);
+      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,