dsh-folia 2.6.0 → 2.9.2

package/lib/client.js

@@ -16231,38 +16231,80 @@ window.__ModuleLoader__.load({
 				}
 
 				/**
-				 * 把一套皮肤的样式**当场**挂进文档。
+				 * 取一套皮肤**最终该用的 CSS**。
+				 *
+				 * 关键：皮肤中心不是把皮肤目录里的 CSS 原样发出去的 ——
+				 *   `GET /api/skin-center/v2/skins/<id>/stylesheet` → `transformSkinCss()`：**强制作用域化**
+				 *   `GET /api/skin-center/v2/skins/<id>/patches`    → 同上（无则 404）
+				 * 作用域化 = 把每条规则包进 `html[data-dsh-skin="<id>"]`。这一步直接决定成败：
+				 * **包了作用域的规则特异性更高**，才压得过应用自身的面板/令牌规则。我们早先注入的是
+				 * 目录里的裸 CSS，特异性与应用同级 ⇒ 大量规则输掉 ⇒ 配色变了一点、面板依旧不透明。
 				 *
-				 * 为什么是 `<style>` 而不是 `<link>`：
-				 *   · `<link rel=stylesheet>` 是**异步**的，加载完成的时机不定，容易输给皮肤中心随后
-				 *     重新注入的那份；
-				 *   · `<style>` 一赋值就参与样式计算，且追加到 `<body>` **末尾** ⇒ 文档顺序最后，
-				 *     同等特异性下后写的赢。这是"不刷新换肤"能真正看见的关键。
+				 * 所以优先**直接用它加工好的那份**（同源，浏览器自带凭证）；只有拿不到才退回我们自己的
+				 * `/folia/skins/css`（未作用域化，能变配色但压不住应用规则）。
+				 *
+				 * @returns {Promise<{ css: string, source: string }>}
+				 */
+				async function fetchSkinCss(id) {
+				  const enc = encodeURIComponent(id);
+				  const parts = [];
+				  let source = "";
+
+				  // ① 宿主端代理由它自己去问皮肤中心（带上本次请求的 Cookie 与同源头）。
+				  //    前端直连 `/api/skin-center/...` 会被 DSH 网关挡掉，实测一直落到"未作用域化"。
+				  try {
+				    const viaHost = await apiFetch("/skins/scoped-css?id=" + enc, { parse: false, cache: "no-store" });
+				    if (viaHost && viaHost.ok && viaHost.response) {
+				      const text = await viaHost.response.text();
+				      if (text && text.trim()) return { css: text, source: "skin-center" };
+				    }
+				  } catch { /* 代理不可用 ⇒ 继续走下面两条 */ }
+
+				  // ② 前端直连（皮肤中心同源路由，能通的话最省一次往返）
+				  for (const part of ["stylesheet", "patches"]) {
+				    try {
+				      // 根相对路径 + 原生请求：桌面壳可能跑在 `dsh-app://` 下（`location.origin` 是 "null"），
+				      // 拼绝对 URL 会作废；`/api/...` 交给浏览器按文档解析才可靠
+				      //（皮肤中心自己的客户端用的也是这种写法）。
+				      const r = await apiRawResponse("/api/skin-center/v2/skins/" + enc + "/" + part);
+				      if (r && r.ok) {
+				        const text = await r.text();
+				        if (text && text.trim()) {
+				          parts.push(text);
+				          source = "skin-center";
+				        }
+				      }
+				    } catch { /* 拿不到就试下一段 / 退回自己的路由 */ }
+				  }
+				  if (parts.length > 0) return { css: parts.join("\n/* ---- patches ---- */\n"), source };
+				  const r2 = await apiFetch("/skins/css?id=" + enc + "&t=" + Date.now(), { parse: false, cache: "no-store" });
+				  if (!r2 || !r2.ok || !r2.response) throw new Error("css-http-" + ((r2 && r2.status) || 0));
+				  const text = await r2.response.text();
+				  if (!text || !text.trim()) throw new Error("css-empty");
+				  return { css: text, source: "folia-raw" };
+				}
+
+				/**
+				 * 把一套皮肤的样式**当场**挂进文档。
 				 *
-				 * 仍然不跑 `hooks.mjs`（粒子等动效），那部分只有整页重载才生效。
+				 * 用 `<style>` 而不是 `<link>`：`<style>` 一赋值就参与样式计算，且追加到 `<body>` 末尾
+				 * ⇒ 文档顺序最后、同等特异性下后写的赢；`<link>` 是异步的，顺序不由我们定。
 				 *
 				 * @param {string} id 皮肤 id
-				 * @returns {Promise<{ bytes: number, rules: number }>}
+				 * @returns {Promise<{ bytes: number, rules: number, source: string }>}
 				 */
 				async function applySkinCss(id) {
-				  const resp = await apiFetch("/skins/css?id=" + encodeURIComponent(id) + "&t=" + Date.now(), {
-				    parse: false,
-				    cache: "no-store",
-				  });
-				  if (!resp || !resp.ok || !resp.response) throw new Error("css-http-" + ((resp && resp.status) || 0));
-				  const css = await resp.response.text();
-				  if (!css || !css.trim()) throw new Error("css-empty");
+				  const { css, source } = await fetchSkinCss(id);
 				  let el = document.getElementById("folia-skin-hot");
 				  if (!el) {
 				    el = document.createElement("style");
 				    el.id = "folia-skin-hot";
-				    // 挂 body 末尾（不是 head）：文档顺序最后 ⇒ 同等特异性下覆盖先前的规则。
 				    (document.body || document.head).appendChild(el);
 				  }
 				  el.textContent = css;
 				  let rules = 0;
 				  try { rules = (el.sheet && el.sheet.cssRules && el.sheet.cssRules.length) || 0; } catch { /* 读不到就报 0 */ }
-				  return { bytes: css.length, rules };
+				  return { bytes: css.length, rules, source };
 				}
 
 				/**
@@ -16320,12 +16362,13 @@ window.__ModuleLoader__.load({
 				  }
 				  el.src = pick.url;
 				  // 皮肤 CSS 通过 `> img` / `> video` 选中它 ⇒ 必须是**直接子元素**。
+				  el.setAttribute("aria-hidden", "true");
 				  el.style.cssText = "position:absolute;inset:0;width:100%;height:100%;object-fit:cover;";
 				  layer.appendChild(el);
 
 				  if (pick.scrim) {
 				    const scrim = document.createElement("div");
-				    scrim.style.cssText = "position:absolute;inset:0;pointer-events:none;background-image:" + pick.scrim + ";";
+				    scrim.style.cssText = "position:absolute;inset:0;pointer-events:none;background:" + pick.scrim + ";";
 				    layer.appendChild(scrim);
 				  }
 
@@ -16337,7 +16380,230 @@ window.__ModuleLoader__.load({
 				  return { kind: pick.type };
 				}
 
-				function SkinsTabPanel() {
+				/* ── 热切换运行时：作用域属性 + 六个装饰层 + hooks ───────────────────────────────
+				 *
+				 * 皮肤不是"一份 CSS"。它有三层，缺一层就"显示不全"：
+				 *   ① 样式：`stylesheet` + `patches`
+				 *   ② 背景：`contributes.backgroundMedia`
+				 *   ③ 作用域与装饰层：`html[data-dsh-skin="<id>"]` + 六个 `[data-dsh-skin-layer=...]`
+				 *
+				 * 第 ③ 项是"大部分皮肤看起来没生效"的真正原因 —— 65 套里有 **30 套**把规则整段挂在
+				 * `html[data-dsh-skin]` 下面，属性不设，那些规则一条都不匹配；另有 **28 套**带
+				 * `hooks.mjs`（粒子/交互），契约见皮肤中心 `contracts/hooks-api.d.ts`：
+				 *   apply({ skinId, scopeAttr, assetBase, layers{...}, theme{get,subscribe}, onCleanup })
+				 * 所以这里补齐作用域属性、六个层，并按契约跑 hooks（失败只降级）。
+				 */
+
+				const SKIN_LAYER_NAMES = ["background", "ambient", "bottom", "sidebar", "top", "foreground"];
+				/**
+				 * 六层的**精确**样式：逐字对齐皮肤中心 `runtime/decoration-layers.ts` 的 `LAYER_STYLE`。
+				 *
+				 * 不能自己拍脑袋定层级 —— 它的注释写明了为什么：
+				 *   · background 用 **-2**：负 z-index 元素画在 html/body 背景**之上**（皮肤自己的
+				 *     不透明底色因此在画后面、艺术图在它前面），但**在所有面板之下**；
+				 *   · ambient 30、top/bottom/sidebar 40、foreground 41：压在面板之上、官方浮层
+				 *     （>=1000）之下。之前我把非背景层留成 auto ⇒ 装饰条落进文档流最底层，
+				 *     表现正是"上面被面板盖住、只有下面露出背景"。
+				 */
+				const SKIN_LAYER_STYLE = {
+				  background: "position:fixed;top:0;right:0;bottom:0;left:0;z-index:-2;pointer-events:none;will-change:transform;",
+				  ambient: "position:fixed;top:0;right:0;bottom:0;left:0;z-index:30;pointer-events:none;",
+				  top: "position:fixed;top:0;left:0;right:0;z-index:40;pointer-events:none;",
+				  bottom: "position:fixed;bottom:0;left:0;right:0;z-index:40;pointer-events:none;",
+				  sidebar: "position:fixed;top:0;bottom:0;left:0;z-index:40;pointer-events:none;",
+				  foreground: "position:fixed;top:0;right:0;bottom:0;left:0;z-index:41;pointer-events:none;",
+				};
+				/** 本次激活注册的清理函数（切换皮肤时逐个跑掉，幂等）。 */
+				let skinHotCleanups = [];
+
+				function skinThemeNow() {
+				  try {
+				    return (document.body && document.body.hasAttribute("data-ds-dark-theme")) ? "dark" : "light";
+				  } catch {
+				    return "light";
+				  }
+				}
+
+				/** 建立/复用六个装饰层，返回契约里那个 `layers` 对象。 */
+				function ensureSkinLayers() {
+				  const host = document.body || document.documentElement;
+				  const out = {};
+				  for (const name of SKIN_LAYER_NAMES) {
+				    let el = null;
+				    try { el = document.querySelector('[data-dsh-skin-layer="' + name + '"]'); } catch { el = null; }
+				    if (!el) {
+				      el = document.createElement("div");
+				      el.setAttribute("data-dsh-skin-layer", name);
+				      el.setAttribute("aria-hidden", "true");
+				      host.appendChild(el);
+				    }
+				    // 与它的 ensureOne 同口径：**每次都对已有层重写样式** —— 皮肤中心的层可能带着
+				    // 上一次激活留下的内联覆盖，只建不改会继承脏值。
+				    el.style.cssText = SKIN_LAYER_STYLE[name];
+				    out[name] = el;
+				  }
+				  // 皮肤中心自己会给 body 盖 `data-dsh-skin-center`（它的若干基础样式挂在这个前缀下），
+				  // 缺了它，面板/列表那些"表面透明"的规则不生效 → 大片面板仍然不透明。
+				  try { document.body.setAttribute("data-dsh-skin-center", ""); } catch { /* ignore */ }
+				  return out;
+				}
+
+				/**
+				 * 按契约跑一套皮肤的 hooks。失败**只降级**（返回原因），绝不打断样式/背景。
+				 * @returns {Promise<{ ran: boolean, reason?: string }>}
+				 */
+				async function applySkinHooks(id) {
+				  const resp = await apiJson("/skins/manifest?id=" + encodeURIComponent(id));
+				  const doc = (resp && resp.data) || null;
+				  const rel = doc && doc.hooks;
+				  if (!rel) return { ran: false, reason: "no-hooks" };
+
+				  const encoded = String(rel).split("/").map(encodeURIComponent).join("/");
+				  const r = await apiFetch("/skins/files/" + encodeURIComponent(id) + "/" + encoded, {
+				    parse: false,
+				    cache: "no-store",
+				  });
+				  if (!r || !r.ok || !r.response) return { ran: false, reason: "hooks-http-" + ((r && r.status) || 0) };
+				  const source = await r.response.text();
+				  if (!source || !source.trim()) return { ran: false, reason: "hooks-empty" };
+
+				  const blobUrl = URL.createObjectURL(new Blob([source], { type: "text/javascript" }));
+				  try {
+				    const mod = await import(blobUrl);
+				    const factory = mod && typeof mod.default === "function" ? mod.default : null;
+				    if (!factory) return { ran: false, reason: "no-default-export" };
+				    const hooks = factory();
+				    if (!hooks || typeof hooks.apply !== "function") return { ran: false, reason: "no-apply" };
+
+				    const layers = ensureSkinLayers();
+				    const unsubs = [];
+				    const ctx = {
+				      skinId: id,
+				      scopeAttr: id,
+				      assetBase: apiUrl("/skins/files/" + encodeURIComponent(id) + "/"),
+				      layers,
+				      theme: {
+				        get: skinThemeNow,
+				        subscribe(listener) {
+				          try {
+				            const obs = new MutationObserver(() => {
+				              try { listener(skinThemeNow()); } catch { /* 监听方出错不影响别人 */ }
+				            });
+				            obs.observe(document.body, { attributes: true, attributeFilter: ["data-ds-dark-theme"] });
+				            const off = () => { try { obs.disconnect(); } catch { /* ignore */ } };
+				            unsubs.push(off);
+				            return off;
+				          } catch {
+				            return () => {};
+				          }
+				        },
+				      },
+				      onCleanup(fn) { if (typeof fn === "function") skinHotCleanups.push(fn); },
+				    };
+				    hooks.apply(ctx);
+				    if (typeof hooks.dispose === "function") {
+				      skinHotCleanups.push(() => { try { hooks.dispose(); } catch { /* 幂等 */ } });
+				    }
+				    skinHotCleanups.push(() => { for (const off of unsubs) { try { off(); } catch { /* ignore */ } } });
+				    return { ran: true };
+				  } finally {
+				    setTimeout(() => { try { URL.revokeObjectURL(blobUrl); } catch { /* ignore */ } }, 10000);
+				  }
+				}
+
+				/** 撤掉上一次热切换留下的东西（清理函数 + 注入样式）。作用域属性由下一次直接覆盖。 */
+				function clearSkinHot() {
+				  for (const fn of skinHotCleanups.splice(0).reverse()) {
+				    try { fn(); } catch { /* 清理幂等，单个失败不影响其余 */ }
+				  }
+				  try {
+				    const el = document.getElementById("folia-skin-hot");
+				    if (el) el.remove();
+				  } catch { /* ignore */ }
+				}
+
+				/**
+				 * 把一套皮肤**完整**应用上去（作用域 + 六层 + 样式 + 背景 + hooks）。
+				 * 按钮和"壁纸撤下后自动恢复"走的是**同一个**函数 —— 两条路径不能各写一遍。
+				 */
+				async function applySkinHot(id) {
+				  clearSkinHot();
+				  try { document.documentElement.setAttribute("data-dsh-skin", id); } catch { /* ignore */ }
+				  ensureSkinLayers();
+				  const info = await applySkinCss(id);
+				  const bg = await applySkinBackground(id);
+				  let hooksInfo = { ran: false, reason: "skipped" };
+				  try {
+				    hooksInfo = await applySkinHooks(id);
+				  } catch (e) {
+				    hooksInfo = { ran: false, reason: String((e && e.message) || e) };
+				  }
+				  return { info, bg, hooks: hooksInfo };
+				}
+
+				/** 把皮肤**整个撤掉**，回到应用原生外观（壁纸接管背景时走这条）。 */
+				function teardownSkin() {
+				  clearSkinHot();
+				  try { document.documentElement.removeAttribute("data-dsh-skin"); } catch { /* ignore */ }
+				  try { document.body.removeAttribute("data-dsh-skin-center"); } catch { /* ignore */ }
+				  for (const name of SKIN_LAYER_NAMES) {
+				    try {
+				      const el = document.querySelector('[data-dsh-skin-layer="' + name + '"]');
+				      if (el) el.innerHTML = "";
+				    } catch { /* ignore */ }
+				  }
+				}
+
+				/** 向宿主问"当前选中的皮肤是哪个"（没选中返回空串）。 */
+				async function activeSkinIdFromHost() {
+				  try {
+				    const resp = await apiJson("/skins");
+				    const doc = (resp && resp.data) || null;
+				    return (doc && typeof doc.active === "string") ? doc.active : "";
+				  } catch {
+				    return "";
+				  }
+				}
+
+				let skinArbiterStarted = false;
+				/**
+				 * **皮肤与壁纸互斥的仲裁器**（两个方向都要管）。
+				 *
+				 * 现状：点「使用」时我们会主动清掉壁纸（一个方向）；但用户**反过来**点壁纸时，
+				 * 没人撤掉我们热注入的皮肤 —— 于是皮肤那层不透明样式压在壁纸上面，壁纸看起来被"遮挡"。
+				 *
+				 * 这里盯 `body[data-we-wallpaper]` 这个标记（**壁纸插件自己在挂/摘**，是双方共同的事实源）：
+				 *   · 标记出现 ⇒ 撤掉皮肤（teardownSkin）
+				 *   · 标记消失 ⇒ 若选中过皮肤，重新完整应用（applySkinHot）
+				 * 这样无论用户先点哪边，最后都是"只有一个在台"。
+				 */
+				function startSkinArbiter() {
+				  if (skinArbiterStarted) return;
+				  const body = (typeof document !== "undefined") ? document.body : null;
+				  if (!body) { setTimeout(startSkinArbiter, 400); return; }
+				  skinArbiterStarted = true;
+				  let seq = 0;
+				  const sync = async () => {
+				    const mine = ++seq;
+				    const wallpaperOn = body.hasAttribute("data-we-wallpaper");
+				    if (wallpaperOn) { teardownSkin(); return; }
+				    const id = await activeSkinIdFromHost();
+				    if (mine !== seq) return;                 // 期间又变了，放弃这次
+				    if (!id) return;
+				    try { await applySkinHot(id); } catch { /* 失败就保持原生外观 */ }
+				  };
+				  try {
+				    new MutationObserver(() => { sync().catch(() => {}); })
+				      .observe(body, { attributes: true, attributeFilter: ["data-we-wallpaper"] });
+				    // 启动时就跑一次：处理"上次退出时壁纸在台、皮肤被让位"这类残留状态
+				    sync().catch(() => {});
+				  } catch { /* 环境不支持观察就只保留按钮路径 */ }
+				}
+
+				function SkinsTabPanel(props) {
+				  // 壁纸让位：挂载点（设置页 / 首页抽屉）各自把"清掉当前壁纸"的回调传进来 ——
+				  // 皮肤和壁纸都在铺背景，必须二选一。本组件不直接碰设置，只调用传进来的入口。
+				  const onClearWallpaper = props && props.onClearWallpaper;
 				  const [list, setList] = React.useState([]);
 				  const [active, setActive] = React.useState(null);
 				  const [loading, setLoading] = React.useState(true);
@@ -16399,18 +16665,23 @@ window.__ModuleLoader__.load({
 				          setNote({ kind: "ok", text: weT("已安装：") + label });
 				          await load(true);
 				        } else if (kind === "activate") {
-				          // **当场换肤**：把皮肤样式同步注入文档，不刷新、不重启。
-				          // 注入结果直接写进提示里（字节数 / 规则条数）：万一样式还是没盖住皮肤中心，
-				          // 这一行就是判断"是没注入"还是"注入了但被压住"的依据，不用再猜。
+				          // **当场换肤**：作用域 + 六层 + 样式 + 背景 + hooks，全在 applySkinHot 里
+				          //（与"壁纸撤下后自动恢复"共用同一实现，两条路径不会漂移）。
 				          let info = null;
 				          let applyErr = "";
 				          let bgKind = "none";
+				          let hooksInfo = { ran: false, reason: "skipped" };
 				          try {
-				            info = await applySkinCss(id);
-				            // 样式之后立刻搭背景层：没有它，凡是靠 backgroundMedia 的皮肤（水墨丹青、
-				            // 鲸鱼娘、深海女仆工坊…）都只会"变配色不变画面"。
-				            const bg = await applySkinBackground(id);
-				            bgKind = bg.kind;
+				            // ① 壁纸先让位：清掉 `id` 之后壁纸层撤下、`data-we-wallpaper` 消失，
+				            //    皮肤中心也不会再扣住皮肤。（反方向由 startSkinArbiter 负责。）
+				            if (typeof onClearWallpaper === "function") {
+				              try { await Promise.resolve(onClearWallpaper()); } catch { /* 清不掉也继续换肤 */ }
+				            }
+				            // ② 应用皮肤
+				            const applied = await applySkinHot(id);
+				            info = applied.info;
+				            bgKind = applied.bg.kind;
+				            hooksInfo = applied.hooks;
 				          } catch (e) {
 				            applyErr = String((e && e.message) || e);
 				          }
@@ -16420,8 +16691,11 @@ window.__ModuleLoader__.load({
 				              ? weT("已切换为「") + label + weT("」，但样式注入失败：") + applyErr
 				              : weT("已切换到「") + label + weT("」—— 样式 ")
 				                + Math.round(info.bytes / 1024) + " KB / " + info.rules + weT(" 条规则")
-				                + (bgKind === "none" ? weT("，该皮肤无背景媒体") : weT("，背景：") + bgKind),
-				            // hooks（粒子等动效）只有整页重载才会跑：给一个可选入口，不强制。
+				                + (info.source === "skin-center" ? weT("（已作用域化）") : weT("（未作用域化，可能显示不全）"))
+				                + (bgKind === "none" ? weT("，无背景媒体") : weT("，背景：") + bgKind)
+				                + (hooksInfo.ran ? weT("，动效已启动") : (hooksInfo.reason === "no-hooks" ? weT("，无动效") : weT("，动效未启动(") + hooksInfo.reason + ")"))
+				                + (typeof onClearWallpaper === "function" ? weT("，壁纸已关闭") : ""),
+				            // hooks 已经跑过了；这里只作为"整页重载"的可选入口（极少数皮肤依赖启动期布局）
 				            reload: true,
 				          });
 				          // 不再整表重拉：本地标记已经对了，省掉那 600 ms 的"没反应"窗口。
@@ -16636,11 +16910,20 @@ window.__ModuleLoader__.load({
 				  return React.createElement(React.Fragment, null, children);
 				}
 
-				/** 页签薄包装：`renderActiveTab` 只认这个签名（与别的 `render*Tab(ctx)` 一致）。 */
-				function renderSkinsTab(ctx) {
-				  return React.createElement(SkinsTabPanel, null);
+				/**
+				 * 页签薄包装：`renderActiveTab` 只认这个签名（与别的 `render*Tab(ctx)` 一致）。
+				 * 传进来的 `props` 原样转交给组件 —— 目前只有 `onClearWallpaper`（皮肤与壁纸互斥，
+				 * 由挂载点提供"清掉当前壁纸"的入口；本文件不直接碰设置）。
+				 */
+				function renderSkinsTab(props) {
+				  return React.createElement(SkinsTabPanel, props || null);
 				}
 
+				// 模块加载即启动互斥仲裁（不依赖用户是否打开过皮肤包页签）：
+				//   壁纸在台 ⇒ 撤掉皮肤；壁纸撤下 ⇒ 恢复选中的皮肤。
+				// 放在模块作用域而不是 React effect 里，是因为它必须在**任何面板渲染之前**就守住这个不变量。
+				try { startSkinArbiter(); } catch { /* 环境异常时退化为纯按钮路径 */ }
+
 				// ── 内联模块：src/picker-model.js —— 选择器模型层：过滤判定 + 派生数据 + 分页切片（纯函数 / 显式入参 / 零 DOM）（构建期注入；勿手改本段）──
 				/**
 				 * picker-model.js — 壁纸选择器的**模型层**：过滤判定 + 派生数据 + 分页切片。
@@ -18247,7 +18530,7 @@ window.__ModuleLoader__.load({
 				            ? qpRenderPlaybackPane(sel, switchQpTab)
 				            // 皮肤包：直接挂设置页那个同一个组件（它自己管列表/下载/激活状态）。
 				            : qpTab === "skins"
-				              ? React.createElement(SkinsTabPanel, null)
+				              ? React.createElement(SkinsTabPanel, { onClearWallpaper: () => setSetting("id", "") })
 				              : null),
 				        !(qpTab === "wallpaper" && userPropsPanelOpen() && propsAvailable) && qpTab === "wallpaper" && React.createElement(React.Fragment, null,
 				                // ── 壁纸列表（搜索 + 视图切换 + 快切）──
@@ -22614,6 +22897,34 @@ window.__ModuleLoader__.load({
 				/** DELETE（多数接口不返回体；需要时传 parse: true）。 */
 				const apiDelete = (path, options) => apiFetch(path, Object.assign({ method: 'DELETE', parse: false }, options));
 
+				/**
+				 * 根相对路径的**原生**请求（**不补 BASE**），返回原始 `Response`（失败给 null）。
+				 *
+				 * 用途：访问**同源其它插件**的路由 —— 典型是皮肤中心的 `/api/skin-center/v2/...`
+				 *（它把皮肤 CSS 做了强制作用域化，只有那条路由给的版本才能压过应用自身规则）。
+				 *
+				 * 为什么必须是**根相对路径**而不是 `location.origin + path`：桌面壳里文档可能跑在
+				 * 自定义协议下（`dsh-app://…`），此时 `location.origin` 是 `"null"`，拼出来的绝对 URL
+				 * 直接作废。`/api/...` 交给浏览器按文档解析，两种协议下都成立 —— 皮肤中心自己的客户端
+				 * 用的也正是这种写法。
+				 *
+				 * @param {string} path 以 `/` 开头的同源路径
+				 * @param {{ method?: string, cache?: string, headers?: object, fetch?: Function }} [options]
+				 * @returns {Promise<Response|null>}
+				 */
+				async function apiRawResponse(path, options) {
+				  const o = options || {};
+				  const doFetch = pickFetch(o.fetch);
+				  if (!doFetch) return null;
+				  const init = { method: o.method || 'GET', cache: o.cache || 'no-store' };
+				  if (o.headers) init.headers = o.headers;
+				  try {
+				    return await doFetch(String(path), init);
+				  } catch {
+				    return null;
+				  }
+				}
+
 				// ── 内联模块：src/occlusion.js —— 遮挡投递：/occlusion 轮询 + 缩放 + postMessage（1Hz，含退避与可见性暂停）（构建期注入；勿手改本段）──
 				/**
 				 * occlusion.js — Linux 壳窗遮挡的**客户端轮询器**：宿主 `/occlusion` 快照 → 画布局部
@@ -29865,7 +30176,7 @@ window.__ModuleLoader__.load({
 		    if (activeTab === "extensions") return renderExtensionsTab(extensionCtx());
 		    // 「皮肤包」自带异步状态（列表 / 下载中 / 错误），所以它是一个**真组件**而不是
 		    // 纯渲染函数 —— 薄包装只负责挂上去（理由见 src/panel-tabs-skins.js 文件头）。
-		    if (activeTab === "skins") return renderSkinsTab();
+		    if (activeTab === "skins") return renderSkinsTab({ onClearWallpaper: () => setSetting("id", "") });
 		    if (activeTab === "appearance") return renderAppearanceTab({
 		      setSetting, setTransient,
 		      fontSet: fontSetCtx(),

package/lib/routes/skins.js

@@ -646,6 +646,103 @@ export function registerSkinRoutes(webServer, c) {
     },
   }));
 
+  /* ── 路径式素材路由 ────────────────────────────────────────────────────────
+   * 皮肤的 hooks 契约（`contracts/hooks-api.d.ts`）给的是 `assetBase`：一个**同源 URL
+   * 前缀**，hooks 里自己拼 `assetBase + 'assets/x.webp'`。`?id=&p=` 这种查询式前缀拼不出
+   * 合法地址，所以这里再提供一条路径式：`/skins/files/<id>/<相对路径>`。
+   * 与 asset 完全同一套安全校验（id 白名单 + 路径段 + 越界检查）。
+   */
+  disposers.push(webServer.register({
+    kind: 'prefix',
+    path: `${base}/skins/files`,
+    handler: async (req, res) => {
+      let pathname = '/';
+      try { pathname = new URL(req.url || '/', 'http://x').pathname; } catch { res.statusCode = 400; res.end(); return; }
+      const prefix = `${base}/skins/files/`;
+      if (!pathname.startsWith(prefix)) { res.statusCode = 404; res.end(); return; }
+      const rest = decodeURIComponent(pathname.slice(prefix.length));
+      const slash = rest.indexOf('/');
+      const id = slash < 0 ? rest : rest.slice(0, slash);
+      const rel = slash < 0 ? '' : rest.slice(slash + 1);
+      if (!ID_RE.test(id)) { res.statusCode = 400; res.end(); return; }
+      const segs = safeRelPath(rel);
+      if (!segs || segs.includes('..')) { res.statusCode = 400; res.end(); return; }
+      const harness = harnessRoot();
+      if (!harness) { res.statusCode = 503; res.end(); return; }
+      const root = join(harness, SKINS_DIR_NAME, id);
+      const file = join(root, ...segs);
+      if (!resolve(file).startsWith(resolve(root) + sep)) { res.statusCode = 400; res.end(); return; }
+      if (!existsSync(file) || !statSync(file).isFile()) { res.statusCode = 404; res.end(); return; }
+      const ext = (file.slice(file.lastIndexOf('.')).toLowerCase() || '');
+      res.setHeader('Content-Type', ASSET_TYPES[ext] || 'application/octet-stream');
+      res.setHeader('Cache-Control', 'public, max-age=300');
+      res.end(readFileSync(file));
+    },
+  }));
+
+  /* ── 皮肤中心「加工后 CSS」的宿主端代理 ──────────────────────────────────────
+   * 皮肤中心的 `/skins/<id>/stylesheet|patches` 是 `transformSkinCss()` 的产物：
+   * **每条规则被强制包进 `html[data-dsh-skin="<id>"]`**，特异性高于应用自身规则 ——
+   * 只有那份 CSS 才能真正把面板压透。皮肤目录里的原始 CSS 压不住，于是"显示不全"。
+   *
+   * 为什么需要代理：浏览器直接请求 `/api/skin-center/v2/...` 被 DSH 网关挡掉
+   *（实测前端一直落到"未作用域化"的降级分支）。宿主端在本机回环上再发一次、并**带上
+   * 浏览器这次请求的 Cookie 与同源头**，就能拿到那份产物。
+   *
+   * 拿不到（皮肤中心没装 / 该皮肤不在它的 catalog 里）一律 404，客户端据此回退到原始 CSS。
+   */
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${base}/skins/scoped-css`,
+    handler: async (req, res) => {
+      const url = new URL(req.url || '/', 'http://x');
+      const id = url.searchParams.get('id') || '';
+      if (!ID_RE.test(id)) { res.statusCode = 400; res.end(); return; }
+      const host = req && req.headers && req.headers.host;
+      if (!host) { res.statusCode = 500; res.end(); return; }
+      const origin = 'http://' + host;
+      // 透传**全部**入站头（网关认的是这次会话的凭证，可能是 cookie，也可能是某个自定义
+      // 头；只挑几个字段必漏），再去掉逐跳头并补上同源语义。
+      // 实测：裸请求与"只带 sec-fetch-*"都回 401 ⇒ 凭证不在这几个头里。
+      const HOP_BY_HOP = new Set([
+        'host', 'connection', 'keep-alive', 'transfer-encoding', 'upgrade', 'te', 'trailer',
+        'proxy-authorization', 'proxy-authenticate', 'content-length', 'accept-encoding',
+      ]);
+      const fwdHeaders = {};
+      for (const [k, v] of Object.entries(req.headers || {})) {
+        const key = k.toLowerCase();
+        if (HOP_BY_HOP.has(key)) continue;
+        if (typeof v === 'string') fwdHeaders[key] = v;
+        else if (Array.isArray(v)) fwdHeaders[key] = v.join(', ');
+      }
+      fwdHeaders.origin = origin;
+      fwdHeaders.referer = origin + '/';
+      fwdHeaders['sec-fetch-site'] = 'same-origin';
+      fwdHeaders['sec-fetch-mode'] = 'cors';
+      fwdHeaders['sec-fetch-dest'] = 'empty';
+      fwdHeaders.accept = 'text/css,*/*;q=0.1';
+
+      for (const part of ['stylesheet', 'patches']) {
+        try {
+          const r = await fetch(origin + '/api/skin-center/v2/skins/' + encodeURIComponent(id) + '/' + part, {
+            headers: fwdHeaders,
+            signal: AbortSignal.timeout(SKINS_TIMEOUT_MS),
+          });
+          if (!r.ok) continue;
+          const text = await r.text();
+          if (!text || !text.trim()) continue;
+          res.setHeader('Content-Type', 'text/css; charset=utf-8');
+          res.setHeader('Cache-Control', 'no-store');
+          res.setHeader('X-Folia-Scoped', '1');
+          res.end(text);
+          return;
+        } catch { /* 这一段失败就试下一段 */ }
+      }
+      res.statusCode = 404;
+      res.end();
+    },
+  }));
+
   disposers.push(webServer.register({
     kind: 'exact',
     path: `${base}/skins/asset`,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-folia",
-    "version":  "2.6.0",
+    "version":  "2.9.2",
     "description":  "Folia 壁纸引擎：把本机 Wallpaper Engine 壁纸搬进 DSH 界面（场景实时渲染 / 视频 / 网页），内置液态玻璃与 Folia 吉祥物，并可从自建站点拉取壁纸。单包形态（组件已合并）。",
     "type":  "module",
     "engines":  {