dsh-folia 4.12.4 → 4.13.0

package/cordis.patch.yml

@@ -1,23 +1,23 @@
 # dsh-plugin-folia bundle patch.
 #
-# Row set: this bundle + the skin centre it brings along.
+# ⚠️ 这里**只有一条** row。皮肤中心由桌面端/市场自己那条 row 负责，我们不再插第二条（见下）。
 #
-# ── 为什么这里有第二条 row ──────────────────────────────────────────────────
-# 我们不再自己实现皮肤渲染：皮肤包（`skin.json` + `skin.css` + 可选 `hooks.mjs`）由
-# `@linxin666/dsh-client-ui-skin-center` 加载与启用，我们的「助手皮肤」页签只负责把站点 zip
-# 解到它读的那个目录（`$DSH_HOME/skins`）。所以它必须是**装得上的**：本包把它列为
-# `dependencies`，并在下面插一条 row —— 用户装 dsh-folia 就同时得到两件套，不用再单独装。
+# ── 为什么不再声明 skin-center 的 row 与依赖（2026-10-30 实测）─────────────────
+# 我们一厢情愿地"随身携带"皮肤中心（`dependencies` + 第二条 insert row），结果与桌面端自己
+# 管理的同一条 row 撞了：`.dsh-market/log.ndjson` 每次启动都会写
 #
-# ── 重复 row 为什么不会打起来（实测依据，不是猜测）────────────────────────
-# 1) 宿主半边：它的 `apply` 走 `mountOnce('@linxin666/dsh-client-ui-skin-center', …)`，
-#    以 `globalThis[Symbol.for('dsh-web.mounted-plugins')]` 记账 ⇒ 第二次挂载是空操作，
-#    不会重复注册 webserver 路由。
-# 2) 客户端半边：它的设置分区注册包在 `try { ctx.slots.register(...) } catch { return () => {} }`，
-#    重复注册被吞掉 ⇒ 不会出现两张「皮肤」设置页。
-# 于是「用户已有 dsh-web-all（它也插了一条 row）」与「只用我们」两种情形都成立。
+#     "@linxin666/dsh-client-ui-skin-center -> off: fiber=true"
+#     "plugin kept off: @linxin666/dsh-client-ui-skin-center"
 #
-# 版本：依赖写 `^0.4.8`（本仓实测过的版本线）；它若大改 v1alpha1 契约，我们跟着升级即可。
-# 判据：test/verify-skin-center-bundle.mjs 会同时钉住「声明了依赖」与「插了唯一 id 的 row」。
+# 也就是**它被关掉了**，于是 `/api/skin-center/v2/*` 整族变成路由 miss（带会话实测：404），
+# 「助手皮肤」页签里点「应用」必然失败。把依赖钉到 0.4.8 只在那一次启动里生效，桌面端重启后
+# 会把 0.4.12 投影回来（engines 要求 `dsh >= 0.2.1-rc.3`，而当前桌面端是 rc.2）→ 又被关掉。
+# 直接改 profile 的 package.json / overrides 会让桌面端"Profile 恢复未完成"进安全模式 —— 那条路
+# 我们已经走过一次并回滚，不再重复。
+#
+# 结论：**不由我们替用户装这个插件**。它该由用户在自己的插件市场/桌面端里装（那里管版本与引擎
+# 匹配），我们的页签只做两件事：把站点 zip 解到 `$DSH_HOME/skins`，以及在它确实在跑时写选择。
+# 判据见 test/verify-skin-center-bundle.mjs：**只允许一条 row**，且不得再声明为依赖。
 #
 # A patch replaces the targeted row's whole `config`, so only additive `insert`
 # rows appear here (we never override an existing shipped row).
@@ -25,13 +25,3 @@
 - insert:
     - id: folia
       name: 'dsh-folia'
-    # 皮肤中心：独立 npm 包（BSD-3-Clause），本包作为依赖携带。
-    #
-    # ⚠️ row id **不能**以 `folia-` 开头：`lib/subpackage-boot.js#subpackageSpecifiers` 把
-    #    「id 以 `folia-` 开头的行」当作**我们自己的子包行**做启动自检（解析不到就抛，因为宿主
-    #    对行级失败是静默的）。给第三方行起 `folia-skin-center` 这种 id 会被误判成"我们的子包"
-    #    ⇒ 自检去仓库 node_modules 里解析它，开发树里没有这个依赖就直接抛，整个 apply 失败。
-    #    所以这里用不撞前缀的 `skin-center`（也与 web-all 的 `web-ui-skin-center`、
-    #    官方包的 `ui-skin-center` 都不同名）。
-    - id: skin-center
-      name: '@linxin666/dsh-client-ui-skin-center'

package/lib/client.js

@@ -18317,14 +18317,24 @@ window.__ModuleLoader__.load({
 				      const resp = await apiJson("/skins/list" + (force ? "?refresh=1" : ""), { parse: "always" });
 				      const doc = (resp && resp.data) || null;
 				      if (resp && resp.ok && doc && doc.ok) {
-				        // 读"当前在用哪套皮肤"必须**由浏览器发**，不能走宿主代理：
-				        // `/api/skin-center/v2/*` 的读写被 DSH 自己的会话鉴权挡着，宿主 fetch 没有 cookie ⇒ 401。
-				        // 路径用**相对 `/api/...`**：不要拼 `location.origin` —— 我们跑在宿主页面里，origin 不一定
-				        // 等于宿主 HTTP API 的源；拼错会得到一个不存在的地址，而它的 404 还会被误读成业务 404。
-				        // api-client 对 `/api/**` 原样放行（不补 /folia 前缀）。
+				        // 皮肤中心在不在跑，**由浏览器判定**，不信宿主探测的结论。
+				        // 宿主 fetch 不带会话：`/api/**` 一旦被鉴权挡在前面就只会拿到 401，而 401 既可能是
+				        // "装了但需要会话"也可能是"路由没挂载"，从宿主那一侧**无法区分**（实测踩过：
+				        // 报文纯 401 就把整个页签的「应用」按钮锁死）。浏览器同源请求天然带会话，
+				        // 拿得到就是真在跑，拿不到再退回宿主给的三态。
+				        if (doc.skinCenter !== "present") {
+				          try {
+				            const cat = await apiJson("/api/skin-center/v2/catalog", { parse: "always" });
+				            if (cat && cat.ok && cat.data && cat.data.ok) doc.skinCenter = "present";
+				          } catch { /* 仍旧用宿主给的状态 */ }
+				        }
+				        // 读"当前在用哪套皮肤"：**先直连**（同源相对路径 `/api/**`，凭据天然带全），
+				        // 直连不通（页面的 origin 可能不等于宿主 HTTP 服务的 origin ⇒ 路由没到）再退回宿主代理
+				        // `/folia/skins/active` —— 代理会把浏览器这一侧的 cookie 与同源头转发过去。
 				        if (doc.skinCenter === "present") {
 				          try {
-				            const a = await apiJson("/api/skin-center/v2/active", { parse: "always" });
+				            let a = await apiJson("/api/skin-center/v2/active", { parse: "always" });
+				            if (!(a && a.ok)) a = await apiJson("/skins/active", { parse: "always" });
 				            if (a && a.ok) doc.active = (a.data && a.data.active) || "";
 				          } catch { /* 读不到就显示"无使用中" */ }
 				        }
@@ -18361,18 +18371,38 @@ window.__ModuleLoader__.load({
 				            return;
 				          }
 				        }
-				        // 切换皮肤**由浏览器直接写**皮肤中心自己的端点（同源、自带会话）；
-				        // 走宿主代理会 401 —— DSH 对 `/api/skin-center/v2/*` 的读写都做会话鉴权，宿主 fetch 没有 cookie。
-				        // 统一走 api-client（不裸 fetch），路径用相对 `/api/...`（不拼 location.origin ——
-				        // 拼错会得到一个不存在的地址，404 又会被误读成业务 404）。
-				        const resp = await apiPostJson("/api/skin-center/v2/active", { active: wantId }, { parse: "always" });
+				        // 写入有两条路，**先直连、再代理**：
+				        //   ① 直连：相对 `/api/skin-center/v2/active`（同源、凭据天然带全）。
+				        //      前提是页面的 origin 就是宿主 HTTP 服务那个源；桌面端内嵌页面的 origin 未必是它 ⇒ 路由没到 ⇒ 404。
+				        //   ② 代理：`/folia/skins/activate`，宿主把浏览器这侧的 cookie 与同源头转发给皮肤中心。
+				        //      这条在"origin 不一致"时仍然成立，所以作为兜底存在。
+				        // 两条都失败时把两边的状态码都显示出来 —— 下一次不用再猜是哪一段断的。
+				        const direct = await apiPostJson("/api/skin-center/v2/active", { active: wantId }, { parse: "always" });
+				        let resp = direct;
+				        if (!(resp && resp.ok)) {
+				          resp = await apiPostJson("/skins/activate", { id: wantId || "" }, { parse: "always" });
+				        }
 				        if (!(resp && resp.ok)) {
-				          // 把响应体里的 error 一起显示：`skin-not-found`（它的 catalog 不收）与"路径不对"
-				          // 从状态码上看都是 404，只有 body 能分开（实测踩过：把 URL 拼错当成了业务 404）。
-				          const detail = (resp && resp.data && resp.data.error) ? ":" + resp.data.error : "";
-				          setNote({ ok: false, text: weT("操作失败：{code}", { code: "skin-center-" + ((resp && resp.status) || 0) + detail }) });
+				          const up = (resp && resp.data && resp.data.upstream) || null;
+				          const det = (up && up.error) ? ":" + up.error
+				            : ((resp && resp.data && resp.data.error) ? ":" + resp.data.error : "");
+				          setNote({
+				            ok: false,
+				            text: weT("操作失败：{code}", {
+				              code: "direct=" + ((direct && direct.status) || 0) + " proxy=" + ((resp && resp.status) || 0) + det,
+				            }),
+				          });
 				          return;
 				        }
+				        // 关键：让**皮肤赢**。皮肤中心检测到 `body[data-we-wallpaper]` 时会**主动停画**
+				        // （它的 withhold 合约：壁纸在台时它不上台），所以"写成功但画面不变"完全合理 ——
+				        // 用户在这个页签点「应用」，意图就是让皮肤接管外观，因此这里主动进入「皮肤让路」态：
+				        // 清掉我们的壁纸层 + 摘下玻璃门控（client.js 里既有的 enterSkinYield，记忆会落盘，
+				        // 点「恢复默认外观」时按记忆放回壁纸）。
+				        try {
+				          if (wantId && typeof enterSkinYield === "function") enterSkinYield("folia-tab-apply");
+				          if (!wantId && typeof exitSkinYield === "function") exitSkinYield("folia-tab-clear");
+				        } catch { /* 让路是增强：失败也不影响皮肤中心的写入 */ }
 				        // 两条收敛路径：① 广播皮肤中心自己监听的 `dsh-skin-applied`（立即就地切换）；
 				        // ② 它另外每 2 秒轮询 /api/skin-center/v2/active（事件丢了也会在 2 秒内跟上）。
 				        try {
@@ -18380,7 +18410,9 @@ window.__ModuleLoader__.load({
 				        } catch { /* 老环境没有 CustomEvent 也无所谓，②会兜住 */ }
 				        setNote({
 				          ok: true,
-				          text: wantId ? weT("已切换到：{name}", { name: label || "" }) : weT("已恢复官方默认外观"),
+				          text: wantId
+				            ? weT("已切换到：{name}（本插件的壁纸与玻璃已让位）", { name: label || "" })
+				            : weT("已恢复官方默认外观（壁纸已按记忆放回）"),
 				        });
 				        await load(true);
 				        return;
@@ -18436,21 +18468,33 @@ window.__ModuleLoader__.load({
 				  //   不在 → 明说它是个**独立插件**（不在 dsh-web-all 里），给一条可复制的安装命令
 				  //   unknown（探测失败）→ 保守地按"在"讲，不吓唬用户
 				  const skinCenter = (state && state.skinCenter) || "unknown";
+				  // `present` 是**唯一**允许点「应用」的状态：只有真的拿到 catalog JSON 才算它在跑。
+				  // `absent`=路由不存在（插件没装/未启用）；`auth-gated`=鉴权在路由前面挡住（无法判定）；
+				  // `unknown`=探测失败。后三种都如实告诉用户"现在点应用不会成功"，而不是让他点了看 404。
+				  const canApply = skinCenter === "present";
 				  if (skinCenter === "absent") {
 				    children.push(React.createElement("div", {
 				      key: "hint-absent",
 				      className: "we-picker__hint",
 				      style: { margin: "6px 0 4px", color: "#ffd08a", lineHeight: "1.6" },
-				    }, weT("皮肤中心没装：它是**独立插件** @linxin666/dsh-client-ui-skin-center（不在 dsh-web-all 里，那个只是聚合包）。装它才能启用皮肤：")));
+				    }, weT("皮肤中心**没在运行**（它的 /api/skin-center/v2/* 路由不存在）。它是独立插件 @linxin666/dsh-client-ui-skin-center；常见原因是版本与当前桌面端不匹配 —— 0.4.9+ 要求 dsh ≥ 0.2.1-rc.3，而本机是 rc.2，市场会把这条行保持为 off。装/降级到 0.4.8 即可：")));
 				    children.push(React.createElement("div", { key: "cmd", style: { display: "flex", gap: "8px", alignItems: "center", margin: "0 0 6px" } },
 				      React.createElement("code", {
 				        style: { fontSize: "11px", padding: "3px 8px", borderRadius: "6px", background: "rgba(255,255,255,0.08)" },
-				      }, "dsh plugin --profile web add @linxin666/dsh-client-ui-skin-center"),
+				      }, "dsh plugin --profile web add @linxin666/dsh-client-ui-skin-center@0.4.8"),
 				      React.createElement("button", {
 				        className: "we-picker__btn", type: "button",
-				        onClick: () => { try { navigator.clipboard.writeText("dsh plugin --profile web add @linxin666/dsh-client-ui-skin-center"); setNote({ ok: true, text: weT("已复制安装命令") }); } catch { setNote({ ok: false, text: weT("复制失败，请手动选中上面的命令") }); } },
+				        onClick: () => { try { navigator.clipboard.writeText("dsh plugin --profile web add @linxin666/dsh-client-ui-skin-center@0.4.8"); setNote({ ok: true, text: weT("已复制安装命令") }); } catch { setNote({ ok: false, text: weT("复制失败，请手动选中上面的命令") }); } },
 				      }, weT("复制命令")),
 				    ));
+				  } else if (skinCenter === "auth-gated" || skinCenter === "unknown") {
+				    children.push(React.createElement("div", {
+				      key: "hint-unknown",
+				      className: "we-picker__hint",
+				      style: { margin: "6px 0 4px", color: "#ffd08a", lineHeight: "1.6" },
+				    }, skinCenter === "auth-gated"
+				      ? weT("读不到皮肤中心的清单（浏览器侧也被鉴权挡住）。先点一次「刷新」；仍不行就说明它没在运行 —— 去设置里确认皮肤中心已启用。")
+				      : weT("皮肤中心状态未知（探测超时/网络错误）。点「刷新」重试。")));
 				  } else {
 				    children.push(React.createElement("div", {
 				      key: "hint",
@@ -18458,6 +18502,8 @@ window.__ModuleLoader__.load({
 				      style: { margin: "6px 0 4px", opacity: 0.8 },
 				    }, weT("本页签可以直接切换皮肤：装完点「应用」即可，无需打开设置页。皮肤包落在皮肤中心目录，两边读同一份。")));
 				  }
+				  // 皮肤中心不在跑时，「应用」按钮直接禁用并给出原因 —— 比"点了报错"诚实。
+				  const applyBlockedReason = canApply ? "" : weT("读不到皮肤中心的清单，先点「刷新」；仍不行说明它没在运行");
 
 				  // 提示行常驻占位（与开机动画/桌宠页签同一条纪律：不因 note 出现/消失让面板跳高度）
 				  children.push(React.createElement("div", {
@@ -18526,7 +18572,8 @@ window.__ModuleLoader__.load({
 				              ? React.createElement("span", { style: { ...SKIN_STYLE.badge, background: "rgba(60,160,90,0.55)" } }, weT("使用中"))
 				              : React.createElement("button", {
 				                className: "we-picker__btn", type: "button",
-				                disabled: Boolean(busy),
+				                disabled: Boolean(busy) || !canApply,
+				                title: applyBlockedReason || undefined,
 				                onClick: () => act("activate", { id: s.id }, s.name),
 				              }, busyThis ? weT("切换中…") : weT("应用")),
 				            React.createElement("button", {
@@ -18572,7 +18619,8 @@ window.__ModuleLoader__.load({
 				                  : React.createElement("button", {
 				                    key: "apply",
 				                    className: "we-picker__btn", type: "button",
-				                    disabled: Boolean(busy),
+				                    disabled: Boolean(busy) || !canApply,
+				                    title: applyBlockedReason || undefined,
 				                    onClick: () => act("activate", { id: localId }, s.title),
 				                  }, busy === "activate:" + localId ? weT("切换中…") : weT("应用")),
 				                React.createElement("span", { key: "done", style: SKIN_STYLE.badge }, weT("已安装")),
@@ -18591,6 +18639,170 @@ window.__ModuleLoader__.load({
 				  return React.createElement("div", { className: "we-picker", style: { display: "flex", flexDirection: "column" } }, children);
 				}
 
+				// ── 内联模块：src/skin-compat.js —— 皮肤兼容层：把宿主槽位翻成分栏词表（data-pane / data-dsh-frame）—— 皮肤包写的是 web-all 的 compat 标记，没装 web-all 时否则整套选择器不命中（构建期注入；勿手改本段）──
+				/**
+				 * 皮肤兼容层：把宿主（stock DSH）的**槽位词表**翻译成皮肤包认的**分栏词表**。
+				 *
+				 * 为什么需要它（实测，不是推测）：
+				 *   · 皮肤包的 CSS 大量使用 `[data-pane="sidebar"]` / `[data-pane="conversation"]` /
+				 *     `[data-pane="details"]` / `[data-dsh-frame]`。样例计数（按行）：
+				 *     verdandi 60+、xp 36+、deep-current 12、cafe-roastery 10、ember-fall 6、blueprint 4 …
+				 *     全catalog 里 `data-pane=` 出现 250+ 次。
+				 *   · 但**这些属性不是宿主写的**，是 `@linxin666/dsh-web-all` 的 compat shim 写的：
+				 *     web-all/lib/client.js 的 `COLUMN_SHIMS = [["[class*=\"sidebarCol\"]","data-pane=\"sidebar\""], …]`
+				 *     而皮肤中心自己也写明："the `data-pane=\"conversation\"` attribute is stamped by the
+				 *     dsh-web-all compat shim"（skin-center/lib/client.js:4171 附近的注释）。
+				 *   ⇒ 没装 web-all 时，这些选择器**一条都不命中**：皮肤不是"坏了"，是它认的分栏标记不在。
+				 *     症状就是"皮肤显示不全"（布局/侧栏/输入区没被皮肤接管），而装了 web-all 就正常。
+				 *
+				 * 我们的做法：**只读宿主槽位，补写分栏属性**。
+				 *   · `[data-slot="sidebar"]` → 它的父元素（`div.[class*=sidebarCol]`）标 `data-pane="sidebar"`
+				 *   · `[data-slot="main"]`    → 它的父元素（`div.[class*=centerCol]`）标 `data-pane="conversation"`
+				 *   · `[data-slot="rightbar"]` → 它的父元素（`div.[class*=rightbarCol]`）标 `data-pane="details"`
+				 *   · `#root` 下的画框元素 → `data-dsh-frame`
+				 *
+				 * ⚠️ **锚点必须取"列那一级"的槽名**（sidebar / main / rightbar），取深层槽名是无效的：
+				 *   宿主 `renderSlot` 的锚点是 `ANCHOR_STYLE = { display: "contents" }` 的**无布局包裹元素**
+				 *   与列容器之间的嵌套（app.asar 实证，JSX 顺序即 DOM 顺序）：
+				 *
+				 *     div.frame
+				 *       ├ div.sidebarCol   ← children: renderSlot("sidebar")        ⇒ 锚点的父元素就是列
+				 *       ├ div.centerCol    ← children: renderSlot("main")           ⇒ 同上
+				 *       └ div.rightbarCol  ← children: renderSlot("rightbar")       ⇒ 同上
+				 *
+				 *   而 `main.conversation` 是 `main` 的子槽（`ConversationPanel` 里 renderSlot），
+				 *   `rightbar.session` 更在 `div.session` 之内 ⇒ 它们的**父元素是另一个 display:contents 锚点
+				 *   或内层包裹 div**，把 data-pane 写在那里既没有布局效果、也不是方案认的那一列。
+				 *   ⇒ 所以这里既用列级槽名，又让 `paneHost` **穿过 `[data-slot]` 锚点**再落笔；
+				 *     深层槽名只作退路（宿主哪天不再给列级槽名时仍能命中）。
+				 *
+				 * 三条纪律（与仓库既有的跨插件协议一致）：
+				 *   ① **只写自己的标记**：不碰皮肤中心的 `data-dsh-skin` / `data-dsh-surface` / 任何 `data-we-*`；
+				 *   ② **幂等**：已存在同名属性就不改（别人（web-all）先写过就以它为准）；
+				 *   ③ **可失败**：整段包在 try 里，异常绝不影响壁纸/玻璃主路径；观察器只在 document 就绪后装。
+				 *
+				 * 属性本身是惰性的（宿主 CSS 不用 data-pane），所以可以在启动时就补，不必等皮肤上台。
+				 */
+
+				const PANE_ANCHORS = [
+				  // 列级槽名优先（实证：这三种锚点的父元素就是列容器）。
+				  { pane: 'sidebar', selectors: ['[data-slot="sidebar"]'] },
+				  { pane: 'conversation', selectors: ['[data-slot="main"]', '[data-slot="main.conversation"]'] },
+				  { pane: 'details', selectors: ['[data-slot="rightbar"]', '[data-slot="rightbar.session"]', '[data-sidebar-right-panel]'] },
+				];
+
+				/** 从锚点元素上溯（穿过 display:contents 的 `[data-slot]` 锚点），得到"那一列"的容器。 */
+				function paneHost(anchor) {
+				  let el = anchor && anchor.parentElement;
+				  // 宿主的槽位锚点都是 display:contents 包裹元素（renderSlot 的 ANCHOR_STYLE），
+				  // 属性写在它身上没有布局效果 ⇒ 必须一直走到第一个"真盒子"。
+				  let guard = 0;
+				  while (el && el.hasAttribute && el.hasAttribute('data-slot') && guard < 12) {
+				    el = el.parentElement;
+				    guard += 1;
+				  }
+				  if (!el || el === document.body) return null;
+				  if (el.id === 'root') return null;
+				  if (el.hasAttribute('data-dsh-frame')) return null;
+				  return el;
+				}
+
+				function stampPanes() {
+				  let stamped = 0;
+				  for (const rule of PANE_ANCHORS) {
+				    // 每条规则**各自**判断有没有命中：早先用累计计数会让后一条规则在第一条选择器空手时
+				    // 直接跳过退路选择器（conversation/details 的退路因此永远不被尝试）。
+				    let ruleStamped = 0;
+				    for (const selector of rule.selectors) {
+				      let nodes;
+				      try { nodes = document.querySelectorAll(selector); } catch { continue; }
+				      for (const node of nodes) {
+				        const host = paneHost(node);
+				        if (!host || host.hasAttribute('data-pane')) continue;
+				        host.setAttribute('data-pane', rule.pane);
+				        stamped += 1;
+				        ruleStamped += 1;
+				      }
+				      if (ruleStamped) break; // 同一 pane 命中一种锚点即可
+				    }
+				  }
+				  return stamped;
+				}
+
+				function stampFrame() {
+				  try {
+				    if (document.querySelector('[data-dsh-frame]')) return 0;
+				    const root = document.getElementById('root') || document.body;
+				    if (!root) return 0;
+				    // 与 web-all 同口径：**列容器的父元素**就是画框（`sidebarCol.parentElement`）；类名只作退路。
+				    const sidebarHost = document.querySelector('[data-pane="sidebar"]');
+				    const fromColumn = (sidebarHost && sidebarHost.parentElement) || null;
+				    const frame = (fromColumn && fromColumn !== document.body && fromColumn.id !== 'root' ? fromColumn : null)
+				      || root.querySelector('div[class*="_frame"]')
+				      || root.firstElementChild;
+				    if (!frame || frame.hasAttribute('data-dsh-frame')) return 0;
+				    if (frame === document.body || frame.id === 'root') return 0;
+				    frame.setAttribute('data-dsh-frame', '');
+				    return 1;
+				  } catch { return 0; }
+				}
+
+				function stampAll() {
+				  try { return stampPanes() + stampFrame(); } catch { return 0; }
+				}
+
+				/**
+				 * 定时器可缺省：**挂载点跑在不保证有定时的宿主里**。
+				 * 实测（2026-10-30，`test/verify-playback-controls.mjs` / `verify-transcode-state.mjs`）：
+				 * 那几个守卫用只实现 `document` 的 fake DOM 直接 apply 客户端，**没有 `setTimeout`** ——
+				 * 这里裸调 `setTimeout` 会 `ReferenceError`，而 `ctx.effect(() => feat.mount())` 不做保护，
+				 * 异常会顺着 apply 链把**整个宿主插件**带崩（一次 17 条判据全红）。
+				 * ⇒ 有就用（优先 `window.setTimeout`，与仓库其它层同口径），没有就**当场做**，绝不抛。
+				 */
+				function scheduleAfter(fn, ms) {
+				  try {
+				    const st = (typeof window !== 'undefined' && typeof window.setTimeout === 'function')
+				      ? window.setTimeout.bind(window)
+				      : (typeof setTimeout === 'function' ? setTimeout : null);
+				    if (!st) { fn(); return null; }
+				    return st(fn, ms);
+				  } catch { try { fn(); } catch { /* ignore */ } return null; }
+				}
+
+				function cancelAfter(id) {
+				  try {
+				    if (id === null || id === undefined) return;
+				    if (typeof clearTimeout === 'function') clearTimeout(id);
+				    else if (typeof window !== 'undefined' && typeof window.clearTimeout === 'function') window.clearTimeout(id);
+				  } catch { /* ignore */ }
+				}
+
+				/** 装上兼容层；返回幂等 teardown（与仓库其它 install* 同形）。整段可失败（异常不外溢）。 */
+				function installSkinCompat() {
+				  if (typeof document === 'undefined') return () => {};
+				  try {
+				    stampAll();
+				    let observer = null;
+				    let timer = null;
+				    const schedule = () => {
+				      if (timer !== null) return;
+				      timer = scheduleAfter(() => { timer = null; stampAll(); }, 120);
+				    };
+				    try {
+				      observer = new MutationObserver(schedule);
+				      // 只观察结构性变化（子树增删）；不观察属性，避免别人改属性时我们无限自激。
+				      observer.observe(document.body, { childList: true, subtree: true });
+				    } catch { observer = null; }
+				    // 宿主是 SPA：路由切换会整块换掉列容器，所以补一次延迟重扫。
+				    const late = scheduleAfter(stampAll, 1500);
+				    return () => {
+				      try { if (observer) observer.disconnect(); } catch { /* ignore */ }
+				      if (timer !== null) { cancelAfter(timer); timer = null; }
+				      cancelAfter(late);
+				    };
+				  } catch { return () => {}; }
+				}
+
 				// ── 内联模块：src/features.js —— 客户端功能注册表：页签条 / 整区面板 / 常驻挂载层。装配点（quick-panel、client.js）只查表，不写功能名（构建期注入；勿手改本段）──
 				/**
 				 * features.js（客户端）— **功能注册表**：页签声明、面板工厂、挂载钩子。
@@ -18639,6 +18851,9 @@ window.__ModuleLoader__.load({
 				 */
 				const WE_FEATURE_MOUNTS = [
 				  { id: "pets", mount: mountPetLayer },
+				  // 皮肤兼容层：补写 `data-pane` / `data-dsh-frame`（皮肤包写的是 web-all 的 compat 词表）。
+				  // 它只写自己的惰性属性、幂等、可失败，所以随墙纸引擎常驻，不依赖皮肤是否在台上。
+				  { id: "skin-compat", mount: installSkinCompat },
 				];
 
 				/** 页签 → 功能归属（宿主清单 lib/features.js 的客户端镜像，供守卫对账）。 */
@@ -27163,9 +27378,13 @@ window.__ModuleLoader__.load({
 		 * 才回收）。所以只认"过一拍还在"的出现：宽限结束时 DOM 仍带标记、且我方确实有要退的东西
 		 * （壁纸在台 ⇒ 清层；或**无壁纸**且设置已就位 ⇒ 只剩玻璃要让）⇒ 才是动作。
 		 * ⚠️ 450ms 必须显著短于对方的 1500ms 宽限，否则真实动作会在我们确认前被它回收。
+		 *
+		 * `opts.forced`：**标记值发生了变化**（换了一套皮肤）—— 那是用户刚做的一次显式动作，
+		 * 不存在"启动上妆"的竞态可言，所以连"我方是否有层"这条腿都不用再问（见 syncSkinYield）。
 		 */
-		function scheduleSkinYieldEnter(reason) {
+		function scheduleSkinYieldEnter(reason, opts) {
 		  if (skinYieldEnterTimer !== null || skinYielded) return;
+		  const forced = !!(opts && opts.forced);
 		  const fire = () => {
 		    skinYieldEnterTimer = null;
 		    try {
@@ -27177,8 +27396,11 @@ window.__ModuleLoader__.load({
 		      //   · 无壁纸腿：没有层可清、也没有竞态可防，但玻璃整族仍盖在皮肤上（玻璃与壁纸
 		      //     正交，data-we-glass-page 恒挂）⇒ 这条腿也要进，否则无壁纸用户中途试穿 /
 		      //     应用皮肤永远摘不掉玻璃（安装期的 adopt 只管启动那一拍）。
-		      const wallMarkerOn = !!(document.body && document.body.hasAttribute("data-we-wallpaper"));
-		      if (!wallMarkerOn && (selection.id || !selection.loaded)) return;
+		      //   · forced（换皮肤 = 用户刚动作）：跳过启动竞态那套判据，直接让路。
+		      if (!forced) {
+		        const wallMarkerOn = !!(document.body && document.body.hasAttribute("data-we-wallpaper"));
+		        if (!wallMarkerOn && (selection.id || !selection.loaded)) return;
+		      }
 		      enterSkinYield(reason + "/dom");
 		    } catch { /* ignore */ }
 		  };
@@ -27222,10 +27444,24 @@ window.__ModuleLoader__.load({
 		  } catch { fire(); }
 		}
 
-		/** 合议当前状态：皮肤"要求上台"且我方确实在台上 ⇒ 退场；持续不在台上则排定复位。 */
+		/** 上次看到的 `data-dsh-skin` 值（null = 还没看过；用于区分"启动上妆"与"用户换了一套"）。 */
+		let skinAttrSeen = null;
+
+		/**
+		 * 合议当前状态：皮肤"要求上台"且我方确实在台上 ⇒ 退场；持续不在台上则排定复位。
+		 *
+		 * **没有优先级，只有"谁最后动的"**（用户明确要求）：
+		 *   · 皮肤标记**值发生变化** = 用户刚换/刚应用了一套皮肤 ⇒ 我方立刻让路（哪怕壁纸正在画）；
+		 *   · 壁纸被选中 = `media-prep` 的钩子会 `exitSkinYield` ⇒ 皮肤侧 withhold、壁纸接管；
+		 *   · 启动那一拍（值没变）= 不改判：我方有壁纸就让壁纸画（皮肤自己 withhold），
+		 *     我方无壁纸且在皮肤上 ⇒ 认领让路态（见 installSkinInterop 的 adoptOnLoaded）。
+		 */
 		function syncSkinYield(reason) {
 		  try {
-		    if (document.documentElement.hasAttribute("data-dsh-skin")) {
+		    const attr = document.documentElement.getAttribute("data-dsh-skin");
+		    const changed = attr !== skinAttrSeen;
+		    skinAttrSeen = attr;
+		    if (attr) {
 		      cancelSkinYieldExit();
 		      // ⚠️ 「我方在台上」有两条腿：壁纸在台（标记在场 ⇒ 有层要让）与无壁纸（设置已就位
 		      //    且 id 为空 ⇒ 只剩玻璃要让）。启动竞态只长在壁纸腿上——对方运行时会先于我们的
@@ -27234,7 +27470,8 @@ window.__ModuleLoader__.load({
 		      //    动作会清掉壁纸（实测报障：有壁纸时刷新掉壁纸）。正确的收场是：让我们的层建起来
 		      //    → 标记挂上 → 对方 watcher 自行 withhold 撤掉皮肤。无壁纸腿没有竞态（没有层可清），
 		      //    随宽限进即可。不是立即退场：先排定一次"过一拍再确认"（见 scheduleSkinYieldEnter）。
-		      scheduleSkinYieldEnter(reason);
+		      //    但 `changed`（换了一套皮肤）是用户的显式动作，不走那套竞态判据（forced）。
+		      scheduleSkinYieldEnter(reason, { forced: changed });
 		      return;
 		    }
 		    cancelSkinYieldEnter();
@@ -27245,6 +27482,9 @@ window.__ModuleLoader__.load({
 		/** 装上互操作（单腿：DOM 观察）；返回幂等 teardown。 */
 		function installSkinInterop() {
 		  if (typeof document === "undefined" || !document.documentElement) return () => {};
+		  // 启动快照：把当前标记记为"已看过"，这样**启动那一拍不会被当成一次换皮肤动作**
+		  // （否则每次刷新都会误判成用户刚应用皮肤，进而清掉壁纸）。
+		  try { skinAttrSeen = document.documentElement.getAttribute("data-dsh-skin"); } catch { skinAttrSeen = null; }
 		  let observer = null;
 		  try {
 		    observer = new MutationObserver(() => syncSkinYield("dom"));
@@ -27254,7 +27494,9 @@ window.__ModuleLoader__.load({
 		  //   · 皮肤在台上（文档交付时 tap 已画）+ 我方**没有**选中的壁纸 ⇒ 本来就该在让路态
 		  //     （玻璃退场）——认领，不清层；记忆从**盘上落的那份**拿（enter 写的
 		  //     skinYieldRestoreId / skinYieldRestoreRotation），没落过盘才退回空记忆；
-		  //   · 皮肤在台上 + 我方有选中的壁纸 ⇒ 壁纸赢（对方的 withhold 会处理皮肤），不动；
+		  //   · 皮肤在台上 + 我方有选中的壁纸 ⇒ **启动不改判**：保持现状（壁纸画、皮肤自己 withhold）。
+		  //     这不是"优先级"，而是启动那一拍没有"谁最后动"的信息；运行期任一方动作都会立刻改判
+		  //     （换皮肤 ⇒ syncSkinYield 的 forced 分支；选壁纸 ⇒ media-prep 的 exitSkinYield）。
 		  //   · 皮肤**已不在**台上 + 我方没有壁纸 + 盘上留着让路记忆 ⇒ 启动复位：按记忆放回
 		  //     （应用关闭期间皮肤被移除 / 卸载的那条路 —— 没有它，记忆落了盘也无人消费）。
 		  // ⚠️ 认领必须等**宿主设置到位**（`selection.loaded`）：本地缓存可能过期（本窗口缓存空、

package/lib/routes/skins.js

@@ -20,7 +20,7 @@
  */
 import { createHash } from 'node:crypto';
 import { inflateRawSync } from 'node:zlib';
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
@@ -42,6 +42,32 @@ function dshHome() {
 /** 皮肤根：与皮肤中心同一个目录（它读 `$DSH_HOME/skins`）。 */
 function skinsRoot() { return join(dshHome(), 'skins'); }
 
+/**
+ * 皮肤中心持久化"当前皮肤"的那个文件。
+ *
+ * 为什么我们会直接写它（兜底路径）：切换皮肤要落到 `/api/skin-center/v2/active`，
+ * 而那条路径 ① 需要 DSH 会话；② 必须打到宿主 HTTP 服务那个源。实测这两点在桌面端内嵌页面里
+ * 都可能不成立（401 / 路由没到），于是"点应用"根本没有可靠的写入通道。
+ * 这个文件是**它自己的持久层**（`{ active, initialized, background }`），它每次 GET 都重新读它，
+ * 并且客户端每 2 秒轮询一次 GET 收敛 —— 所以写这个文件等价于"替它记下选择"，可靠且即时。
+ * 语义上只改 `active` 一个键，其余原样保留。
+ */
+function activeStatePath() { return join(dshHome(), 'skin-center-active.json'); }
+
+/** 把 `active` 写进皮肤中心的持久层（保留其它字段；原子替换，失败不破坏原文件）。 */
+function writeActiveStateFile(id) {
+  const p = activeStatePath();
+  let doc = {};
+  try { doc = JSON.parse(readFileSync(p, 'utf8')) || {}; } catch { doc = {}; }
+  if (typeof doc !== 'object' || Array.isArray(doc)) doc = {};
+  doc.active = id === undefined ? null : id;
+  if (doc.initialized === undefined) doc.initialized = true;
+  const tmp = p + '.folia-tmp';
+  writeFileSync(tmp, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+  renameSync(tmp, p);
+  return doc;
+}
+
 function siteBase() {
   const raw = process.env.DSH_FOLIA_SITE;
   if (typeof raw === 'string' && raw.trim().toLowerCase() === 'off') return null;
@@ -56,20 +82,43 @@ function siteBase() {
  * 前端也能问，但宿主这一侧拿到的结果与"装没装"一一对应，而且不受浏览器缓存/跨源策略影响。
  * 判据用**它自己的 catalog 路由**：该路由不需要鉴权（实测 200），404 就是没装。
  */
-const skinCenterProbe = { at: 0, state: 'unknown' };
+const skinCenterProbe = { at: 0, state: 'unknown', detail: '' };
 async function probeSkinCenter(hostHeader, force) {
   const now = Date.now();
   if (!force && skinCenterProbe.at && now - skinCenterProbe.at < 30000) return skinCenterProbe.state;
   let state = 'unknown';
+  let detail = '';
   if (hostHeader) {
     try {
       const r = await fetch('http://' + hostHeader + '/api/skin-center/v2/catalog', { signal: AbortSignal.timeout(4000) });
-      state = r.status === 404 ? 'absent' : (r.ok ? 'present' : 'present');
-      // 401/403 也说明插件在（只是该路由被别的版本加了鉴权）；只有 404 才代表没装。
-    } catch { state = 'unknown'; }
+      if (r.ok) {
+        // 只有**真的拿到 catalog JSON** 才算在跑。这个判据以前写成"非 404 即 present"，
+        // 而 401 也会落到那一支 —— 但宿主进程没有会话，拿到的 401 只代表"鉴权挡在前面"，
+        // 完全可能是插件被禁用（路由根本没注册）。实测就被它骗过：面板显示"皮肤中心在"，
+        // 点应用却永远 404（真实原因：插件被市场保持为 off）。
+        let doc = null;
+        try { doc = await r.json(); } catch { doc = null; }
+        state = doc && doc.ok ? 'present' : 'auth-gated';
+        detail = state === 'present' ? '' : 'catalog-not-json';
+      } else if (r.status === 401 || r.status === 403) {
+        // 鉴权挡在前面 ⇒ **无法判定**它到底有没有挂载；如实说"不确定"，不要冒充 present。
+        state = 'auth-gated';
+        detail = 'http-' + r.status;
+      } else if (r.status === 404) {
+        state = 'absent';
+        detail = 'route-missing';
+      } else {
+        state = 'unknown';
+        detail = 'http-' + r.status;
+      }
+    } catch (e) {
+      state = 'unknown';
+      detail = (e && e.name) || 'network';
+    }
   }
   skinCenterProbe.at = now;
   skinCenterProbe.state = state;
+  skinCenterProbe.detail = detail;
   return state;
 }
 
@@ -274,6 +323,13 @@ export function registerSkinsRoutes(webServer, c) {
       sendJson(res, 200, {
         ok: true,
         skinCenter,
+        skinCenterDetail: skinCenterProbe.detail || '',
+        // 皮肤中心被"保持为 off"时（peer 版本不匹配等），用户需要知道去改什么。
+        // 这里不动它，只把"它为什么可能不在"说清楚：我们钉的是 0.4.8（peer dsh >= 0.2.1-rc.2），
+        // 0.4.9+ 要求 rc.3，装了更高版本就会被市场关掉。
+        skinCenterHint: skinCenter === 'present'
+          ? ''
+          : 'skin-center-0.4.8',
         siteBase: siteBase(),
         siteError: site.error,
         installed,
@@ -392,6 +448,114 @@ export function registerSkinsRoutes(webServer, c) {
     },
   }));
 
-  // 切换皮肤与"当前皮肤"都由**浏览器**直接读写皮肤中心的 /api/skin-center/v2/active：
-  // DSH 对该路径的读写做会话鉴权（cookie），宿主 fetch 没有会话 ⇒ 代理只会得到 401（实测）。
+  /* ④ 代理皮肤中心的 active 端点（**转发浏览器凭据**）。
+   *
+   * 为什么需要它：写入 `/api/skin-center/v2/active` 有两个前提 ——
+   *   ① 会话（DSH 对这条路径做鉴权）；② 请求打到**宿主 HTTP 服务**那个源。
+   * 浏览器直连是首选（同源相对路径，凭据天然带全）；但当页面的 origin 与宿主 API 的 origin
+   * 不同（桌面端内嵌页面可能是自定义协议或另一个端口），直连会 404 —— 那是**路由没到**，
+   * 而它的 body 里没有 `error` 字段，正好和皮肤中心自己的 404 `skin-not-found` 区分开。
+   *
+   * 所以这里做**兜底**：把浏览器这一侧的 cookie 与同源头一起转发过去。
+   * 只转发必要的头，不转发 `authorization`（避免把别的凭据带进第三方插件）。
+   */
+  const FORWARD_HEADERS = ['cookie', 'origin', 'referer', 'sec-fetch-site', 'sec-fetch-mode'];
+  function forwardedHeaders(req) {
+    const out = {};
+    const src = (req && req.headers) || {};
+    for (const k of FORWARD_HEADERS) {
+      const v = src[k];
+      if (typeof v === 'string' && v) out[k] = v;
+    }
+    // 同源栅栏看的是 Sec-Fetch-Site / Origin 与 Host 的一致性：我们代理出去时 Host 变了，
+    // 所以显式把它标成 same-origin（这正是事实：浏览器是发给"自己这台的宿主"的）。
+    out['sec-fetch-site'] = 'same-origin';
+    return out;
+  }
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${base}/skins/activate`,
+    handler: async (req, res) => {
+      if ((req.method || 'GET').toUpperCase() !== 'POST') { sendJson(res, 405, { ok: false, error: 'method-not-allowed' }); return; }
+      const host = req.headers && req.headers.host;
+      if (!host) { sendJson(res, 400, { ok: false, error: 'no-host' }); return; }
+      const body = await readJsonBody(req);
+      const raw = body && body.id;
+      const requested = (raw === null || raw === undefined || String(raw) === '') ? null : safeSkinId(raw);
+      if (raw !== null && raw !== undefined && String(raw) !== '' && !requested) {
+        sendJson(res, 400, { ok: false, error: 'bad-id' });
+        return;
+      }
+      if (requested && !existsSync(join(skinsRoot(), requested))) {
+        sendJson(res, 404, { ok: false, error: 'not-installed' });
+        return;
+      }
+      let upstream = { status: 0, error: null };
+      try {
+        const r = await fetch('http://' + host + '/api/skin-center/v2/active', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', ...forwardedHeaders(req) },
+          body: JSON.stringify({ active: requested }),
+          signal: AbortSignal.timeout(6000),
+        });
+        const text = await r.text();
+        let doc = null;
+        try { doc = JSON.parse(text); } catch { /* 非 JSON（路由 miss 时常见） */ }
+        upstream = { status: r.status, error: (doc && doc.error) || null };
+        if (r.ok) {
+          sendJson(res, 200, { ok: true, active: requested, via: 'http', upstream });
+          return;
+        }
+      } catch (e) {
+        upstream = { status: 0, error: e && e.name === 'TimeoutError' ? 'timeout' : 'network' };
+      }
+
+      // ── 兜底：直接写它自己的持久层 ────────────────────────────────────────
+      // HTTP 写入不可用（无会话 / 源不一致 / 端点不在）时，写 `skin-center-active.json` 的
+      // `active` 字段：皮肤中心每次 GET 都重读这个文件，客户端又每 2 秒轮询一次 GET，
+      // 所以写文件等价于"替它记下选择"，最迟 2 秒生效；我们同时还会广播 dsh-skin-applied 立即生效。
+      try {
+        writeActiveStateFile(requested);
+        sendJson(res, 200, { ok: true, active: requested, via: 'state-file', upstream });
+      } catch (e) {
+        sendJson(res, 502, {
+          ok: false,
+          error: 'activate-failed',
+          upstream,
+          detail: String((e && e.message) || e).slice(0, 160),
+        });
+      }
+    },
+  }));
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${base}/skins/active`,
+    handler: async (req, res) => {
+      const host = req.headers && req.headers.host;
+      // 先问皮肤中心自己（HTTP），问不到就**读它的持久层** —— 后者是写路径的兜底，
+      // 两边都必须能回答"现在用的是哪套"，否则面板的"使用中"标记会随写入方式漂移。
+      if (host) {
+        try {
+          const r = await fetch('http://' + host + '/api/skin-center/v2/active', {
+            headers: { accept: 'application/json', ...forwardedHeaders(req) },
+            signal: AbortSignal.timeout(5000),
+          });
+          if (r.ok) {
+            const doc = await r.json().catch(() => null);
+            sendJson(res, 200, { ok: true, active: (doc && doc.active) || null, via: 'http' });
+            return;
+          }
+        } catch { /* 落到文件读 */ }
+      }
+      try {
+        let doc = {};
+        try { doc = JSON.parse(readFileSync(activeStatePath(), 'utf8')) || {}; } catch { doc = {}; }
+        sendJson(res, 200, { ok: true, active: doc.active || null, via: 'state-file' });
+      } catch (e) {
+        sendJson(res, 502, { ok: false, error: 'read-failed', detail: String((e && e.message) || e).slice(0, 120) });
+      }
+    },
+  }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-folia",
-  "version": "4.12.4",
+  "version": "4.13.0",
   "description": "Folia 壁纸引擎：把本机 Wallpaper Engine 壁纸搬进 DSH 界面（场景实时渲染 / 视频 / 网页），内置液态玻璃与 Folia 吉祥物，并可从自建站点拉取壁纸。单包形态（组件已合并）。",
   "type": "module",
   "engines": {
@@ -193,7 +193,6 @@
     }
   },
   "dependencies": {
-    "@linxin666/dsh-client-ui-skin-center": "^0.4.8",
     "webwallgl": "^3.0.0",
     "x11": "^4.3.1"
   },