dsh-folia 4.8.1 → 4.9.0

package/lib/client.js

@@ -778,6 +778,19 @@ window.__ModuleLoader__.load({
 				  "Qwen": "Qwen",
 				  "Folia": "Folia",
 				  "…": "…",
+				  // 开机动画：已开启但无选片时的提示（4.8.2）
+				  "已开启，但还没有选片 —— 下载一条后点「使用」": "Enabled, but no clip is selected yet — download one, then press Use",
+
+				  // ── 站点工程包（zip）：点击即解码的文案（4.9.0）──────────────────────────
+				  "正在解码工程包…（首次会下载，之后立即生效）": "Decoding the project package… (downloads on first use, instant afterwards)",
+				  "这个工程包是可执行程序（application），不能当壁纸": "This package is an application, not a wallpaper",
+				  "解码失败：{code}": "Decode failed: {code}",
+				  "已就绪：{name}": "Ready: {name}",
+				  "已解码，但清单里还没出现 —— 点「刷新」重试": "Decoded, but it has not shown up yet — press Refresh",
+				  "{n} 个站点工程包 · 点一下就能当背景（首次会下载）": "{n} site project packages · one click and it becomes your background (downloads on first use)",
+				  "点击解码并应用（首次需下载）": "Click to decode and apply (downloads the first time)",
+				  "解码中…": "Decoding…",
+				  "工程包 · 点击解码": "Project package · click to decode",
 				};
 
 				// ── 内联模块：src/i18n-copy-picker.js —— 英文词表域：壁纸选择器与快捷面板（picker-* · quick-panel · sidebar-right · theme-follow）（构建期注入；勿手改本段）──
@@ -4619,6 +4632,41 @@ window.__ModuleLoader__.load({
 				  /* Scene-wallpaper "实时帧" badge — top-right under the hide button.
 				     作用域钉在**缩略图卡片**里：卡头的可播放计数徽标（.we-picker__card-head 下）
 				     同名，不能被这条 absolute 角标规则盖掉（那一枚走 .we-picker__card-badge 的基样式，行内计数）。 */
+				  /* ── 站点工程包条带（.we-picker__pkg-*）────────────────────────────────────
+				     为什么单列一条：工程包（zip）不能进 <video>，点它要先解码一次。
+				     形态上刻意与网格卡片区分（横向小卡 + 明确的"点击解码"徽标），
+				     避免用户把它当成"点了立刻切的壁纸"而误以为失败。 */
+				  .we-picker__pkg-strip { margin: 6px 0 10px; }
+				  .we-picker__pkg-row {
+				    display: flex; gap: 8px; overflow-x: auto; padding: 2px 0 6px;
+				    scrollbar-width: thin;
+				  }
+				  .we-picker__pkg {
+				    position: relative; flex: 0 0 auto;
+				    width: 168px; padding: 6px;
+				    display: flex; flex-direction: column; gap: 4px;
+				    border-radius: 8px; cursor: pointer;
+				    background: rgba(255, 255, 255, 0.06);
+				    border: 1px solid rgba(255, 255, 255, 0.12);
+				    transition: background 120ms linear, border-color 120ms linear;
+				  }
+				  .we-picker__pkg:hover { background: rgba(255, 255, 255, 0.12); border-color: rgba(255, 255, 255, 0.24); }
+				  .we-picker__pkg.is-busy { opacity: 0.7; cursor: progress; }
+				  .we-picker__pkg-thumb {
+				    display: block; width: 100%; aspect-ratio: 16 / 9;
+				    border-radius: 6px; background-size: cover; background-position: center;
+				    background-color: rgba(0, 0, 0, 0.25);
+				  }
+				  .we-picker__pkg-title {
+				    font-size: 0.72em; line-height: 1.35; max-height: 2.7em;
+				    overflow: hidden; text-overflow: ellipsis;
+				  }
+				  .we-picker__pkg-badge {
+				    font-size: 0.66em; opacity: 0.85;
+				    padding: 1px 6px; border-radius: 4px;
+				    background: rgba(30, 90, 160, 0.55);
+				    align-self: flex-start;
+				  }
 				  .we-picker__card .we-picker__card-badge {
 				    position: absolute; top: 4px; right: 4px; z-index: 1;
 				    padding: 1px 6px; font-size: 0.62em; line-height: 1.6;
@@ -16435,6 +16483,21 @@ window.__ModuleLoader__.load({
 				  );
 				}
 
+				/**
+				 * **可安装的工程包**（站点上的 WE 工程包 zip）：`type === "package"`。
+				 *
+				 * 为什么不并进 `playableList`：网格的语义是"点一下就切过去"，而工程包要先解码一次
+				 * （下载 + 解包 + 登记成 WE 工程目录）才能播。混进网格会让轮播候选与"可播放"计数都失真。
+				 * 所以它自己一档，由选择器在网格上方单独渲染一条条带，点击走 `onPickCard` 的解码分支。
+				 */
+				function packageWallpapers(wallpapers, ratingFilter, typeFilter, hiddenIds, sourceFilter) {
+				  return wallpapers.filter((w) => w && w.type === "package"
+				    && !isHiddenWallpaper(w.id, hiddenIds)
+				    && matchesRatingFilter(w, ratingFilter)
+				    && matchesSourceFilter(w, sourceFilter)
+				    && (typeFilter === "all" || typeFilter === "package" || typeFilter === "video"));
+				}
+
 				/** 已隐藏列表（保持库存顺序）。 */
 				function hiddenWallpapers(wallpapers, hiddenIds) {
 				  return wallpapers.filter((w) => isHiddenWallpaper(w.id, hiddenIds));
@@ -16467,6 +16530,9 @@ window.__ModuleLoader__.load({
 				    typeCounts[w.type] = (typeCounts[w.type] || 0) + 1;
 				  }
 				  const editorList = playableWallpapers(list, ratingFilter, typeFilter, hiddenIds, sourceFilter);
+				  // 工程包条带（见 packageWallpapers 的注释）：只受分级/来源过滤，不受"可播放"闸门影响。
+				  const packageList = packageWallpapers(list, ratingFilter, typeFilter, hiddenIds, sourceFilter)
+				    .filter((w) => !query || String(w.title || "").toLowerCase().indexOf(query) !== -1);
 				  const hiddenList = hiddenWallpapers(list, hiddenIds);
 				  return {
 				    query,
@@ -16475,6 +16541,8 @@ window.__ModuleLoader__.load({
 				    ratingCounts,
 				    typeCounts,
 				    editorList,
+				    packageList,
+				    packageCount: packageList.length,
 				    hiddenList,
 				    sourceCounts,
 				    normalPage: pageSlice(playableList, input.page),
@@ -16731,6 +16799,42 @@ window.__ModuleLoader__.load({
 				      );
 				  }
 
+				  /**
+				   * 站点工程包条带（`type === "package"`）：它们不能被 <video> 播，点一下要先解码。
+				   *
+				   * 为什么不放进网格：网格语义是"点一下就切过去"，包里没有可直接播的媒体；混进去会让
+				   * "可播放 N 张"的计数与轮播候选都失真。所以独立一条，文案也直说"会下载一次"。
+				   */
+				  function renderPackageStrip(ctx) {
+				    const { packageList, packageInstalling, packageNote, sel } = ctx;
+				    if (!packageList || packageList.length === 0) return null;
+				    const cards = packageList.map((w) => React.createElement("div", {
+				      key: "pkg-" + w.id,
+				      role: "button",
+				      tabIndex: 0,
+				      className: "we-picker__pkg" + (packageInstalling === w.id ? " is-busy" : ""),
+				      title: weT("点击解码并应用（首次需下载）"),
+				      onClick: () => ctx.onPickCard(w),
+				      onKeyDown: (e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); ctx.onPickCard(w); } },
+				    },
+				      w.preview ? React.createElement("span", {
+				        className: "we-picker__pkg-thumb",
+				        style: { backgroundImage: "url(" + JSON.stringify(w.preview) + ")" },
+				      }) : null,
+				      React.createElement("span", { className: "we-picker__pkg-title" }, String(w.title || "")),
+				      React.createElement("span", { className: "we-picker__pkg-badge" },
+				        packageInstalling === w.id ? weT("解码中…") : weT("工程包 · 点击解码")),
+				    ));
+				    return React.createElement("div", { className: "we-picker__pkg-strip" },
+				      React.createElement("div", { className: "we-picker__row" },
+				        React.createElement("span", { className: "we-picker__hint" },
+				          weT("{n} 个站点工程包 · 点一下就能当背景（首次会下载）", { n: packageList.length })),
+				      ),
+				      React.createElement("div", { className: "we-picker__pkg-row" }, cards),
+				      packageNote ? React.createElement("span", { className: "we-picker__hint" }, packageNote) : null,
+				    );
+				  }
+
 				  function renderPickerNormalBody(ctx, draft, draftIdSet, normalWin) {
 				    const { sel, playableList, onToggleBatchMode, armedConfirm, onBatchHide, onDisarmConfirm, cdMode, gridRef, query } = ctx;
 				    return React.createElement("div", { className: "we-picker__modal-body" },
@@ -16756,6 +16860,8 @@ window.__ModuleLoader__.load({
 				          weT("隐藏选中的 {n} 张壁纸？可在「已隐藏」中随时恢复。", { n: sel.batchSelected.length }),
 				          onBatchHide, onDisarmConfirm),
 				        renderPickerFilterRow(ctx),
+				        // 工程包条带：在网格之上、过滤行之下 —— 它属于"从这里挑"，但不参与网格的虚拟化计数。
+				        renderPackageStrip(ctx),
 				        React.createElement("div", { ref: cdMode ? undefined : gridRef, className: "we-picker__grid" },
 				          // "Close wallpaper" card — equivalent of the first <option> in the
 				          // select-based UI. Rendered as a <div role="button"> like every other card:
@@ -17127,7 +17233,9 @@ window.__ModuleLoader__.load({
 
 				  async function act(kind, payload, label) {
 				    if (busy) return;
-				    setBusy(payload && payload.id ? payload.id : kind);
+				    // 只有结构性操作（下载 / 选择 / 删除）才锁 UI；开关与参数是幂等的，锁了反而闪。
+				    const structural = kind === "download" || kind === "select" || kind === "remove";
+				    if (structural) setBusy(payload && payload.id ? payload.id : kind);
 				    setTick(0);
 				    setNote(null);
 				    try {
@@ -17139,7 +17247,13 @@ window.__ModuleLoader__.load({
 				        if (kind === "remove") setNote({ ok: true, text: weT("已删除：{name}", { name: label }) });
 				        if (kind === "toggle") setNote({ ok: true, text: payload.enabled ? weT("开机动画已开启") : weT("开机动画已关闭") });
 				        if (kind === "settings") setNote({ ok: true, text: weT("已保存") });
-				        await load(true);
+				        // 开关/参数类：宿主把整份 boot 配置回给我们（{ ok, ...boot }），直接并进 state，
+				        // **不再 load(true) 重拉整表** —— 那次重拉会让所有控件先禁用再恢复，视觉上就是闪一下。
+				        if (kind === "toggle" || kind === "settings") {
+				          setState((prev) => (prev ? { ...prev, ...r } : prev));
+				        } else {
+				          await load(true);
+				        }
 				      } else {
 				        const code = (r && r.error) || "failed";
 				        setNote({ ok: false, text: r && r.detail ? weT("操作失败：{code}（{detail}）", { code, detail: String(r.detail) }) : weT("操作失败：{code}", { code }) });
@@ -17172,13 +17286,18 @@ window.__ModuleLoader__.load({
 				  },
 				  React.createElement("label", { style: { display: "flex", gap: "6px", alignItems: "center", fontSize: "12px" } },
 				    React.createElement("input", {
-				      type: "checkbox", checked: enabled, disabled: Boolean(busy) || !activeId,
+				      type: "checkbox", checked: enabled,
+				        // 不因"还没选片"而禁用：开关本身是幂等的，宿主在无选片时不会注入任何脚本。
+				        // （实测反馈：勾不动，因为此时 activeId 为空 —— 那是把两件事绑在一起了。）
+				        disabled: Boolean(busy),
 				      onChange: (e) => act("toggle", { enabled: e.target.checked }, ""),
 				    }),
 				    weT("启用（下次启动播放）"),
 				  ),
 				  React.createElement("span", { className: "we-picker__hint" },
-				    activeId ? weT("当前：{name}", { name: (clips.find((c) => c.id === activeId) || {}).title || activeId }) : weT("未选择")),
+				    activeId
+				      ? weT("当前：{name}", { name: (clips.find((c) => c.id === activeId) || {}).title || activeId })
+				      : (enabled ? weT("已开启，但还没有选片 —— 下载一条后点「使用」") : weT("未选择"))),
 				  ));
 
 				  children.push(React.createElement("div", { key: "hint", className: "we-picker__hint", style: { margin: "2px 0 6px", opacity: 0.75 } },
@@ -17189,9 +17308,17 @@ window.__ModuleLoader__.load({
 				      weT("候选清单读不到：{msg}", { msg: String(state.error) })));
 				  }
 
-				  if (note) {
-				    children.push(React.createElement("div", { key: "note", className: "we-picker__hint", style: { color: note.ok ? "#8ee6a8" : "#ff9a9a", margin: "4px 0 8px" } }, note.text));
-				  }
+				  // 提示行**常驻且占位**：它出现/消失会改变面板高度，视觉上就是"点一下闪一下"。
+				  // 固定 minHeight 之后文案变了、布局不动。
+				  children.push(React.createElement("div", {
+				    key: "note",
+				    className: "we-picker__hint",
+				    style: {
+				      color: note && !note.ok ? "#ff9a9a" : "#8ee6a8",
+				      margin: "4px 0 8px", minHeight: "18px", lineHeight: "18px",
+				      opacity: note ? 1 : 0, transition: "opacity 120ms linear",
+				    },
+				  }, note ? note.text : "\u00a0"));
 
 				  // 淡出 / 停留
 				  if (state) {
@@ -17348,7 +17475,9 @@ window.__ModuleLoader__.load({
 				  React.useEffect(() => { load(false); }, [load]);
 
 				  const act = async (kind, payload, label) => {
-				    setBusy(kind + ":" + (payload.id || ""));
+				    // 只有安装/卸载/导入这类**结构性**操作才锁 UI；开关与大小是幂等的。
+				    const structural = kind === "install" || kind === "remove" || kind === "import";
+				    if (structural) setBusy(kind + ":" + (payload.id || ""));
 				    setNote(null);
 				    try {
 				      const resp = await apiPostJson("/pets/" + kind, payload || {}, { parse: "always" });
@@ -17358,7 +17487,13 @@ window.__ModuleLoader__.load({
 				        if (kind === "remove") setNote({ ok: true, text: weT("已卸载：{name}", { name: label || "" }) });
 				        if (kind === "import") setNote({ ok: true, text: weT("已导入并启用：{name}", { name: label || "" }) });
 				        if (kind === "config") setNote({ ok: true, text: weT("已保存") });
-				        await load(true);
+				        // config 的响应里带新的 config（{ ok, config }）⇒ 直接并进 state，
+				        // 不再 load(true) 重拉整个清单（那次重拉会让所有按钮先禁用再恢复 = 闪动）。
+				        if (kind === "config" && r && r.config) {
+				          setState((prev) => (prev ? { ...prev, config: r.config } : prev));
+				        } else {
+				          await load(true);
+				        }
 				      } else {
 				        const code = (r && r.error) || "failed";
 				        setNote({ ok: false, text: weT("操作失败：{code}", { code }) });
@@ -17444,13 +17579,16 @@ window.__ModuleLoader__.load({
 				    ),
 				  ));
 
-				  if (note) {
-				    children.push(React.createElement("div", {
-				      key: "note",
-				      className: "we-picker__hint",
-				      style: { color: note.ok ? "rgba(120,220,150,0.95)" : "rgba(255,140,140,0.95)", margin: "2px 0 8px" },
-				    }, note.text));
-				  }
+				  // 与开机动画页签同理：提示行常驻占位，避免开关时整块高度跳动。
+				  children.push(React.createElement("div", {
+				    key: "note",
+				    className: "we-picker__hint",
+				    style: {
+				      color: note && !note.ok ? "rgba(255,140,140,0.95)" : "rgba(120,220,150,0.95)",
+				      margin: "2px 0 8px", minHeight: "18px", lineHeight: "18px",
+				      opacity: note ? 1 : 0, transition: "opacity 120ms linear",
+				    },
+				  }, note ? note.text : "\u00a0"));
 
 				  const btn = (text, onClick, disabled) => React.createElement("button", {
 				    type: "button", className: "we-picker__btn", disabled: Boolean(disabled),
@@ -30347,7 +30485,50 @@ window.__ModuleLoader__.load({
 		};
 		const onBatchCancel = () => { disarmConfirm(); setTransient("batchMode", false); setTransient("batchSelected", []); emit(); };
 		const onSearchInput = (e) => { setTransient("search", e.target.value); emit(); };
+		/**
+		 * 把一个站点工程包**解码成本机 WE 工程目录**并立刻应用（"点一下就用"）。
+		 *
+		 * 为什么放在点击里而不是"先下载再点"：用户要的是"点这张壁纸就是背景"。
+		 * 第一次点会多等几秒（下载 + 解包），之后同一条目已在盘上 ⇒ 宿主直接 reused，几乎瞬时。
+		 */
+		async function installSitePackage(w) {
+		  selection.packageInstalling = w.id;
+		  selection.packageNote = weT("正在解码工程包…（首次会下载，之后立即生效）");
+		  emit();
+		  try {
+		    const res = await apiPostJson("/site-package/install", { url: w.media, name: w.title }, { parse: "always" });
+		    const d = (res && res.data) || null;
+		    if (!(res && res.ok && d && d.ok)) {
+		      const code = (d && d.error) || "failed";
+		      selection.packageNote = code === "application-package"
+		        ? weT("这个工程包是可执行程序（application），不能当壁纸")
+		        : weT("解码失败：{code}", { code: String(code) });
+		      return;
+		    }
+		    await loadInventory();
+		    const list = (selection.inventory && selection.inventory.wallpapers) || [];
+		    const target = list.find((x) => x && x.id === d.id);
+		    if (target) {
+		      selection.packageNote = weT("已就绪：{name}", { name: target.title || w.title || "" });
+		      applySelection(target.id, { fromManual: true });
+		    } else {
+		      selection.packageNote = weT("已解码，但清单里还没出现 —— 点「刷新」重试");
+		    }
+		  } catch (e) {
+		    selection.packageNote = weT("解码失败：{code}", { code: (e && e.message) ? e.message : weT("网络错误") });
+		  } finally {
+		    selection.packageInstalling = "";
+		    emit();
+		  }
+		}
+
 		const onPickCard = (w) => {
+		  // 工程包（站点上的 WE 工程包 zip）：点它不该"切过去"—— 它还不能播。
+		  // 这里的语义是「解码一次，然后切过去」：用户看到的是"点一下就能用"，没有单独的下载步骤。
+		  if (w && w.type === "package" && !selection.batchMode && !(selection.pickerDraft && selection.editing)) {
+		    void installSitePackage(w);
+		    return;
+		  }
 		  // 轮播编辑器的下钻（pickerDraft）：点卡片 = 加入/移出**草稿**，不切当前壁纸；
 		  // 草稿对象被就地增删（与 importPlaylistIntoDraft / 面板编辑器同一口径），
 		  // 「保存」时才由 saveEditingGroup 落盘。
@@ -30696,7 +30877,7 @@ window.__ModuleLoader__.load({
 		  // 进去、把结果取出来 —— 组件体不再就地算这些（分级/类型/隐藏的判定也在那边）。
 		  const {
 		    query, playableList, basePlayable, ratingCounts, typeCounts, sourceCounts, hiddenList,
-		    editorPageView,
+		    packageList, packageCount, editorPageView,
 		  } = pickerModel({
 		    wallpapers: list,
 		    hiddenIds: selection.hiddenIds,
@@ -30869,6 +31050,12 @@ window.__ModuleLoader__.load({
 		        onClear, onRatingFilterChange, onTypeFilterChange, onSourceFilterChange,
 		        onShowNormalView, onShowHiddenView,
 		        onToggleBatchMode, onArmBatchHide, onBatchHide, onBatchCancel, onSearchInput, onPickCard,
+		        // 站点工程包（type=package）：来自上面 pickerModel 的解构值（本作用域已有），
+		        // 点击走 onPickCard 的解码分支（installSitePackage）。
+		        packageList: packageList || [],
+		        packageCount: packageCount || 0,
+		        packageInstalling: sel.packageInstalling || "",
+		        packageNote: sel.packageNote || "",
 		      }) : React.createElement(React.Fragment, null,
 		        // 页签内容 → **每个页签末尾一个重置**（issue #192 用户口径：重置指定选项卡）→
 		        // 全局重置（只在「系统」页签末尾，即设置页里最接近"最底部"的位置）。

package/lib/features.js

@@ -37,6 +37,10 @@ export const FEATURES = [
     role: '本机/上传/站点三源合并成壁纸库；着色、图层、播放与轮换由客户端接管',
     host: [
       'lib/routes/inventory.js',
+      // 站点工程包（WE 工程包 zip）→ 本机 WE 工程目录：点卡片时"解码一次就能用"。
+      // 产物仍是壁纸，所以归壁纸功能；zip 读取器是它专用的安全入口。
+      'lib/routes/site-package.js',
+      'lib/zip-read.js',
       'lib/routes/media-bytes.js',
       'lib/routes/media-derived.js',
       'lib/routes/scene-frame.js',

package/lib/index.js

@@ -158,7 +158,7 @@ const {
   sceneVideoProbeKey, sceneVideoProbeSet, getMediaInfo, ensureDirOnce, customFrameDir, avatarDir,
   mascotDir, ensureUploadDir, transcodeToFps, registerTranscodeWaiter, transcodeCachePathFor,
   transcodeJobs, readUploadMeta, metaEntry, setUploadMeta, removeUploadMeta, resolveUploadFile,
-  setUploadDir, UPLOAD_MAX_BYTES, WEBWALLGL_DIR, WEBWALLGL_PKG_DIR, GLASS_PRESET_BUILTIN_DIR,
+  setUploadDir, getUploadDir, UPLOAD_MAX_BYTES, WEBWALLGL_DIR, WEBWALLGL_PKG_DIR, GLASS_PRESET_BUILTIN_DIR,
   WE_ASSETS_SOURCE_ID, weAssetsAvailable, getWeAssetsDir, setWeAssetsDir, listWeAssetNames,
   userPropsFor, isBetterSidebarLoaded, GPU_FRAME_MAX_BYTES, GPU_FRAME_AREA_TOL, GPU_WRITE_INFLIGHT, gpuFrameFileFor,
   looksLikePng, pngSizeOf, pngDimsOfBuf, sceneFrameSlot, generateVideoPreview, ensureImagePreview,
@@ -294,6 +294,8 @@ export function apply(ctx) {
   registerFeatureRoutes(webServer, {
     disposers, base: BASE, log, mediaOriginApi, buildInventory,
     componentProbe, ensureImagePreview,
+    // 站点工程包安装要落到"当前"存储位置：传访问器，不传值。
+    getUploadDir,
   });
 
   // 启动预热（有意不阻塞）：站点清单与模块索引各拉一次，让第一次打开面板不冷。

package/lib/route-registry.js

@@ -20,6 +20,7 @@ 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 { registerSitePackageRoutes } from './routes/site-package.js';
 
 /**
  * 已迁移的功能族。
@@ -71,6 +72,17 @@ export const FEATURE_ROUTE_FAMILIES = [
     register: registerPetsRoutes,
     deps: (c) => ({ disposers: c.disposers, base: c.base, log: c.log }),
   },
+  {
+    id: 'site-package',
+    file: 'lib/routes/site-package.js',
+    register: registerSitePackageRoutes,
+    // 站点工程包要"解到本机存储位置"，所以必须拿到**上传目录访问器**（不是值快照：
+    // 用户中途改目录后，安装应该落到新目录）。siteBase 缺省时路由自己回落到站点默认基址。
+    deps: (c) => ({
+      disposers: c.disposers, base: c.base, log: c.log,
+      getUploadDir: c.getUploadDir, siteBase: c.siteBase,
+    }),
+  },
 ];
 
 /**

package/lib/routes/inventory.js

@@ -216,15 +216,27 @@ function foliaAbs(base, u) {
  *
  * 站点目录的条目长这样：`{ slug, title, kind: 'dynamic', mime: 'video/mp4', url: '/media/...' }` ——
  * 它没有 `file` 字段，而且 `kind: 'dynamic'` 既可能是视频也可能是有动画的图，所以 mime 最可靠。
+ *
+ * ⚠️ 实测踩过的坑：WE **工程包**（zip）的 `kind` 也是 `dynamic`、`mime` 是 `application/zip`。
+ * 早先的顺序是「kind=dynamic ⇒ video」，于是 56 MB 的 zip 被当成视频塞进 `<video>`，
+ * 用户看到的是「浏览器无法解码这段视频」。⇒ **非 image/ 非 video/ 的 mime 一律不猜视频**，
+ * 而是判成 `package`（可显示、不可播放，客户端会给出明确原因而不是解码失败）。
  */
 function foliaTypeOfEntry(it) {
   const mime = String((it && it.mime) || '').toLowerCase();
   if (mime.startsWith('video/')) return 'video';
   if (mime.startsWith('image/')) return 'image';
+  // 已知的"包"形态：工程包 / 压缩包。它们不是可直接播放的媒体。
+  if (/^application\/(zip|x-zip|x-zip-compressed)$/.test(mime)) return 'package';
   const kind = String((it && it.kind) || '').toLowerCase();
+  const probe = String((it && (it.file || it.url || it.slug)) || '');
+  if (/\.zip$/i.test(probe)) return 'package';
+  // `application/octet-stream` 是"不知道是什么的二进制"：按后缀与 kind 继续判，
+  // 不当成包（上传工具经常把视频标成 octet-stream）。
+  // 其余"有 mime 但不是媒体"的（例如 application/json）一律不猜 —— 宁可丢也不塞进播放器。
+  if (mime && mime !== 'application/octet-stream') return null;
   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;
@@ -269,9 +281,12 @@ function foliaItemFromCatalog(it, base) {
   return {
     id: 'folia-' + (slug || media),
     title: String((it && it.title) || slug || 'Folia'),
-    type,                                   // 'video' | 'image'
+    type,                                   // 'video' | 'image' | 'package'
     contentrating: null,
-    playable: true,
+    // 工程包（zip）不是可直接播放的媒体：标成不可播放，客户端据此**不塞进 <video>**，
+    // 而是显示「工程包 · 暂不支持」的明确说明（而不是让浏览器报解码失败）。
+    playable: type !== 'package',
+    unsupportedReason: type === 'package' ? 'we-package' : null,
     media,                                  // 绝对 URL
     mediaExt: '.' + (extHit ? extHit[1].toLowerCase() : (type === 'video' ? 'mp4' : 'jpg')),
     // 站点目录可能带 preview/poster；图片没封面时用自己当预览，视频没有就留空（卡片会是黑块）
@@ -472,6 +487,9 @@ function warmInventorySiteCache() {
 }
 
 export { warmInventorySiteCache };
+// 类型判定与条目构造导出**只为测试**（test/inventory-types.mjs）：它们是纯函数，
+// 用它做判据比"起一个假站点再走 HTTP"稳定得多 —— 后者要伪造缓存目录与时点。
+export { foliaTypeOfEntry, foliaItemFromCatalog };
 export function registerInventoryRoutes(webServer, c) {
   const { disposers, base: BASE, mediaOriginApi, buildInventory, componentsProbe } = c;
 

package/lib/routes/site-package.js

@@ -0,0 +1,222 @@
+/**
+ * lib/routes/site-package.js — **站点工程包 → 本机工程目录**（点击即解码的那一半）。
+ *
+ * 背景：站点上有大量 wallpaper-engine **工程包**（zip：`project.json` + `scene.pkg` / `*.mp4`）。
+ * 它不能被 `<video>` 直接播 —— 用户看到的是「浏览器无法解码这段视频」。但它们**能**用：
+ * 本机已经用同一套管线渲染着几百个 WE 场景（Steam 创意工坊那批），差别只是文件还压在 zip 里。
+ *
+ * 所以这里只做一件事：**把 zip 解成"本机 WE 工程目录"**，落在存储位置（上传目录）下，
+ * 命名 `up-dir-<短名>-<hash6>`。落盘之后：
+ *   · `lib/upload-dir.js#enumerateUploadsP` 会自动认领它（它认"含 project.json 的目录"），
+ *   · 于是下一次 `/folia/inventory` 里它就变成 `type: scene|video|web` 的普通壁纸，
+ *   · 走现有场景/视频/web 渲染管线播放。
+ *
+ * 客户端因此可以做到「点一下就用」：点卡片 → 本路由解码 → 清单刷新 → 自动选中刚解出来的那条。
+ * 对用户而言没有"下载/安装"这一步，只有第一次点的时候多等一下。
+ *
+ * 安全（每条都有测试）：
+ *   · **只下我们自己的站点**：URL 的 host 必须在白名单里（默认站点基址），挡 SSRF；
+ *   · 只认 zip 魔数，解包走 `lib/zip-read.js`（拒路径穿越、限量、拒炸弹）；
+ *   · 只写 `project.json` + 工程内文件，不写可执行/脚本；
+ *   · 幂等：同 URL 已解过就直接返回同一个 id（不重复占盘）。
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { readZipEntries, safeNameFromUrl } from '../zip-read.js';
+
+export const DEPS = ['disposers', 'base', 'getUploadDir', 'log', 'siteBase'];
+
+/** 下载上限：工程包实测 3–56MB，留到 256MB；再大就不是"点击即用"的场景了。 */
+const MAX_ZIP_BYTES = 256 * 1024 * 1024;
+const DOWNLOAD_TIMEOUT_MS = 120000;
+
+/** 站点的默认基址（与 inventory 同一个真源语义：以 inventory 的解析为准，这里只作兜底）。 */
+const DEFAULT_SITE = 'https://folia-5ve.pages.dev';
+
+/** 把任意 URL 归一成"允许下载的"绝对 URL；不允许就返回 null。 */
+function allowedDownloadUrl(raw, allowHosts) {
+  let u;
+  try { u = new URL(String(raw)); } catch { return null; }
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') return null;
+  const host = u.host.toLowerCase();
+  if (!allowHosts.includes(host)) return null;
+  return u;
+}
+
+/** 流式下载并限量（Content-Length 可能缺失，所以边下边数）。 */
+async function fetchZip(url, maxBytes = MAX_ZIP_BYTES) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), DOWNLOAD_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: ctrl.signal, headers: { accept: 'application/zip,application/octet-stream,*/*' } });
+    if (!res.ok) return { ok: false, error: 'http-' + res.status };
+    const len = Number(res.headers.get('content-length') || 0);
+    if (len && len > maxBytes) return { ok: false, error: 'too-large' };
+    const chunks = [];
+    let total = 0;
+    if (res.body && typeof res.body.getReader === 'function') {
+      const reader = res.body.getReader();
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.length;
+        if (total > maxBytes) { try { await reader.cancel(); } catch { /* ignore */ } return { ok: false, error: 'too-large' }; }
+        chunks.push(Buffer.from(value));
+      }
+    } else {
+      const buf = Buffer.from(await res.arrayBuffer());
+      total = buf.length;
+      if (total > maxBytes) return { ok: false, error: 'too-large' };
+      chunks.push(buf);
+    }
+    const buf = Buffer.concat(chunks);
+    // 魔数：只认 zip（'PK\x03\x04'）与空包（'PK\x05\x06'）。
+    const magic = buf.length >= 4 ? buf.readUInt32LE(0) : 0;
+    if (magic !== 0x04034b50 && magic !== 0x06054b50) return { ok: false, error: 'not-a-zip' };
+    return { ok: true, buf, bytes: total };
+  } catch (e) {
+    return { ok: false, error: e && e.name === 'AbortError' ? 'timeout' : 'network' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** 目录名：`up-dir-<短名>-<hash6>`。短名只留 ASCII（中文标题不进文件名，避免各平台差异）。 */
+function dirNameFor(url, name) {
+  const stem = safeNameFromUrl(url, 'pkg');
+  const hint = String(name || '').replace(/[^a-zA-Z0-9-]/g, '').slice(0, 24);
+  let h = 0;
+  const s = String(url);
+  for (let i = 0; i < s.length; i += 1) h = (h * 31 + s.charCodeAt(i)) >>> 0;
+  const hash = h.toString(16).padStart(6, '0').slice(0, 6);
+  return 'up-dir-' + (hint || stem) + '-' + hash;
+}
+
+/** 读工程描述（project.json）；缺失/坏 JSON 返回 null。 */
+function readProjectJson(dir) {
+  try {
+    const raw = readFileSync(join(dir, 'project.json'), 'utf8');
+    const p = JSON.parse(raw);
+    return p && typeof p === 'object' ? p : null;
+  } catch { return null; }
+}
+
+/**
+ * 解包落盘。只写 zip 里除目录之外的全部条目（工程包里的 scene.pkg / mp4 / tex / json 都需要），
+ * 但**拒绝对可执行文件的写入**：扩展名在白名单外的一律跳过（正常工程包不会带 exe/dll/bat）。
+ */
+const SKIP_EXEC_RE = /\.(exe|dll|bat|cmd|com|scr|ps1|sh|msi|vbs|js|jse|wsf|hta|lnk|jar)$/i;
+
+function extractInto(dir, entries) {
+  mkdirSync(dir, { recursive: true });
+  let written = 0;
+  const skipped = [];
+  for (const e of entries) {
+    if (e.isDir) continue;
+    if (SKIP_EXEC_RE.test(e.name)) { skipped.push(e.name); continue; }
+    const target = join(dir, e.name);
+    const parent = join(target, '..');
+    mkdirSync(parent, { recursive: true });
+    writeFileSync(target, e.data);
+    written += 1;
+  }
+  return { written, skipped };
+}
+
+/**
+ * @param {*} webServer
+ * @param {{ disposers: any[], base: string, getUploadDir: () => string, log?: Function, siteBase?: string }} c
+ */
+export function registerSitePackageRoutes(webServer, c) {
+  const { disposers, base, getUploadDir, log } = c;
+  const siteBase = String(c.siteBase || DEFAULT_SITE);
+  const allowHosts = (() => {
+    try { return [new URL(siteBase).host.toLowerCase()]; } catch { return [new URL(DEFAULT_SITE).host.toLowerCase()]; }
+  })();
+  // 测试注入：允许把 127.0.0.1 加进白名单（只在显式传入时生效）。
+  if (Array.isArray(c.allowHosts)) for (const h of c.allowHosts) allowHosts.push(String(h).toLowerCase());
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${base}/site-package/install`,
+    handler: async (req, res) => {
+      const send = (code, payload) => {
+        res.statusCode = code;
+        res.setHeader('content-type', 'application/json; charset=utf-8');
+        res.end(JSON.stringify(payload));
+      };
+      let body = {};
+      try {
+        const text = await new Promise((resolve, reject) => {
+          let acc = '';
+          req.on('data', (d) => { acc += d; if (acc.length > 64 * 1024) reject(new Error('too-large')); });
+          req.on('end', () => resolve(acc));
+          req.on('error', reject);
+        });
+        body = text ? JSON.parse(text) : {};
+      } catch { send(400, { ok: false, error: 'bad-body' }); return; }
+
+      const url = allowedDownloadUrl(body.url, allowHosts);
+      if (!url) { send(400, { ok: false, error: 'host-not-allowed' }); return; }
+
+      const uploadDir = String(getUploadDir() || '');
+      if (!uploadDir) { send(500, { ok: false, error: 'no-upload-dir' }); return; }
+      const dir = join(uploadDir, dirNameFor(url.toString(), body.name));
+
+      // 幂等：已经解过且工程描述可读 ⇒ 直接返回（"第二次点"应该立刻生效）。
+      const existing = readProjectJson(dir);
+      if (existing && existing.type && existing.type !== 'application') {
+        send(200, { ok: true, reused: true, id: 'up-dir-' + dir.split(/[\\/]/).pop().replace(/^up-dir-/, ''), type: existing.type, title: existing.title || '' });
+        return;
+      }
+
+      const dl = await fetchZip(url.toString());
+      if (!dl.ok) {
+        try { log && log('site-package: download failed ' + dl.error + ' ' + url.toString()); } catch { /* ignore */ }
+        // 状态码要分得清"对面有问题"与"这个包本身有问题"：
+        // 不是 zip ⇒ 422（内容问题，重试也没用）；超限 ⇒ 413；其余（网络/404）⇒ 502。
+        const code = dl.error === 'not-a-zip' ? 422 : (dl.error === 'too-large' ? 413 : 502);
+        send(code, { ok: false, error: dl.error });
+        return;
+      }
+
+      let parsed;
+      try { parsed = readZipEntries(dl.buf); } catch (e) {
+        send(422, { ok: false, error: (e && e.code) || 'bad-zip' });
+        return;
+      }
+      const hasProject = parsed.entries.some((e) => !e.isDir && /^project\.json$/i.test(e.name));
+      if (!hasProject) { send(422, { ok: false, error: 'no-project-json' }); return; }
+
+      // 半途失败要清干净：否则下次 enumerate 会看到一个没有 project.json 的残缺目录。
+      try {
+        rmSync(dir, { recursive: true, force: true });
+        const { written, skipped } = extractInto(dir, parsed.entries);
+        const proj = readProjectJson(dir);
+        if (!proj) { rmSync(dir, { recursive: true, force: true }); send(422, { ok: false, error: 'bad-project-json' }); return; }
+        if (String(proj.type || '') === 'application') {
+          rmSync(dir, { recursive: true, force: true });
+          send(422, { ok: false, error: 'application-package' });
+          return;
+        }
+        send(200, {
+          ok: true,
+          id: 'up-dir-' + dir.split(/[\\/]/).pop().replace(/^up-dir-/, ''),
+          type: String(proj.type || 'scene'),
+          title: String(proj.title || ''),
+          written,
+          skipped: skipped.length,
+          bytes: dl.bytes,
+        });
+      } catch (e) {
+        try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+        send(500, { ok: false, error: 'extract-failed', detail: e && e.message });
+      }
+    },
+  }));
+}
+
+// 只为测试导出（纯函数，不碰 IO）：白名单与目录命名是安全与幂等的两处要点。
+export { allowedDownloadUrl, dirNameFor };

package/lib/zip-read.js

@@ -0,0 +1,142 @@
+/**
+ * lib/zip-read.js — 最小可用的 **zip 读取器**（只读，流式无关，内存里完成）。
+ *
+ * 为什么自己写：站点上的 WE 工程包是普通 zip（store / deflate），我们只需要"把条目读出来"，
+ * 而 Node 没有内置解压。已有的 `lib/routes/pets.js#unzip` 是给宠物包定制的（只收
+ * `sounds/` 前缀、上限几 MB），不适合 56 MB 的工程包；与其在那里放宽，不如抽出通用件。
+ *
+ * 安全纪律（每条都由 `test/zip-read.mjs` 钉住）：
+ *   · **拒路径穿越**：条目名里出现 `..`、绝对路径、盘符、反斜杠穿越 ⇒ 整包拒绝（不是跳过 ——
+ *     一个恶意条目说明这个包不可信，不该"部分解压"）。
+ *   · **限量**：条目数、单条目解压后大小、总解压后大小、压缩比上限（zip bomb）。
+ *   · `data` 一律返回**解压后**字节；调用方只写自己白名单内的条目。
+ */
+
+import { inflateRawSync } from 'node:zlib';
+
+/** 默认上限：够放 336MB 的 scene.pkg，但挡住失控的解压炸弹。 */
+export const ZIP_LIMITS = {
+  maxEntries: 4000,
+  maxEntryBytes: 512 * 1024 * 1024,
+  maxTotalBytes: 768 * 1024 * 1024,
+  // 单条目压缩比上限（解压后 / 压缩后）。正常资源很难超过 200 倍。
+  maxRatio: 200,
+};
+
+/** 条目名是否安全（相对、无穿越）。 */
+export function isSafeZipEntryName(name) {
+  const s = String(name || '');
+  if (!s) return false;
+  if (s.includes('\0')) return false;
+  // 统一分隔符后再判
+  const norm = s.replace(/\\/g, '/');
+  if (norm.startsWith('/')) return false;
+  if (/^[a-zA-Z]:/.test(norm)) return false;         // 盘符
+  const parts = norm.split('/');
+  if (parts.some((p) => p === '..')) return false;
+  return true;
+}
+
+/**
+ * 解析并解压一个 zip（缓冲）。
+ *
+ * @param {Buffer} buf
+ * @param {Partial<typeof ZIP_LIMITS>} [limits]
+ * @returns {{ entries: { name: string, data: Buffer, isDir: boolean }[], skipped: string[] }}
+ * @throws {Error} 带 `code`：`not-a-zip` / `unsafe-entry` / `too-many-entries` / `too-large` / `bad-zip`
+ */
+export function readZipEntries(buf, limits = {}) {
+  const lim = { ...ZIP_LIMITS, ...limits };
+  if (!Buffer.isBuffer(buf) || buf.length < 22) {
+    throw Object.assign(new Error('not a zip'), { code: 'not-a-zip' });
+  }
+  // 本地文件头魔数 'PK\x03\x04'；允许空包 'PK\x05\x06'。
+  const magic = buf.readUInt32LE(0);
+  if (magic !== 0x04034b50 && magic !== 0x06054b50) {
+    throw Object.assign(new Error('not a zip'), { code: 'not-a-zip' });
+  }
+  // 末尾找中央目录结束记录（EOCD），最多回扫 64KB（含注释）。
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65535); i -= 1) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) throw Object.assign(new Error('bad zip: no EOCD'), { code: 'bad-zip' });
+
+  const count = buf.readUInt16LE(eocd + 10);
+  const cdSize = buf.readUInt32LE(eocd + 12);
+  const cdOffset = buf.readUInt32LE(eocd + 16);
+  if (count > lim.maxEntries) {
+    throw Object.assign(new Error('too many entries: ' + count), { code: 'too-many-entries' });
+  }
+  if (cdOffset + cdSize > buf.length) throw Object.assign(new Error('bad zip: CD out of range'), { code: 'bad-zip' });
+
+  const entries = [];
+  const skipped = [];
+  let total = 0;
+  let p = cdOffset;
+  for (let i = 0; i < count; i += 1) {
+    if (p + 46 > buf.length || buf.readUInt32LE(p) !== 0x02014b50) {
+      throw Object.assign(new Error('bad zip: bad CD entry'), { code: 'bad-zip' });
+    }
+    const method = buf.readUInt16LE(p + 10);
+    const compSize = buf.readUInt32LE(p + 20);
+    const uncompSize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const localOffset = buf.readUInt32LE(p + 42);
+    const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+    p += 46 + nameLen + extraLen + commentLen;
+
+    if (!isSafeZipEntryName(name)) {
+      throw Object.assign(new Error('unsafe entry: ' + name), { code: 'unsafe-entry' });
+    }
+    const isDir = name.endsWith('/');
+    if (isDir) { entries.push({ name, data: Buffer.alloc(0), isDir: true }); continue; }
+    if (uncompSize > lim.maxEntryBytes) {
+      throw Object.assign(new Error('entry too large: ' + name), { code: 'too-large' });
+    }
+    total += uncompSize;
+    if (total > lim.maxTotalBytes) throw Object.assign(new Error('archive too large'), { code: 'too-large' });
+
+    // 本地头的名字/额外字段长度可能与中央目录不同 ⇒ 以本地头为准算数据起点。
+    if (localOffset + 30 > buf.length || buf.readUInt32LE(localOffset) !== 0x04034b50) {
+      throw Object.assign(new Error('bad zip: bad local header for ' + name), { code: 'bad-zip' });
+    }
+    const lNameLen = buf.readUInt16LE(localOffset + 26);
+    const lExtraLen = buf.readUInt16LE(localOffset + 28);
+    const dataStart = localOffset + 30 + lNameLen + lExtraLen;
+    const dataEnd = dataStart + compSize;
+    if (dataEnd > buf.length) throw Object.assign(new Error('bad zip: truncated data for ' + name), { code: 'bad-zip' });
+    const raw = buf.subarray(dataStart, dataEnd);
+
+    let data;
+    if (method === 0) {
+      data = Buffer.from(raw);
+    } else if (method === 8) {
+      if (compSize > 0 && uncompSize / compSize > lim.maxRatio) {
+        throw Object.assign(new Error('suspicious compression ratio: ' + name), { code: 'too-large' });
+      }
+      try { data = inflateRawSync(raw); } catch (e) {
+        throw Object.assign(new Error('inflate failed for ' + name + ': ' + e.message), { code: 'bad-zip' });
+      }
+      if (data.length > lim.maxEntryBytes) {
+        throw Object.assign(new Error('entry too large after inflate: ' + name), { code: 'too-large' });
+      }
+    } else {
+      skipped.push(name + ' (method ' + method + ')');
+      continue;
+    }
+    entries.push({ name, data, isDir: false });
+  }
+  return { entries, skipped };
+}
+
+/** 从 URL 末尾推出一个**文件系统安全**的短名（只保留 ASCII 字母数字与连字符）。 */
+export function safeNameFromUrl(url, fallback = 'pkg') {
+  let base = '';
+  try { base = String(new URL(url).pathname).split('/').filter(Boolean).pop() || ''; } catch { base = ''; }
+  const stem = base.replace(/\.[a-z0-9]{1,6}$/i, '');
+  const ascii = stem.replace(/[^a-zA-Z0-9-]/g, '');
+  return (ascii || fallback).slice(0, 40);
+}

package/package.json

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