dsh-folia 1.6.0 → 2.0.0

package/lib/components/about-notice/index.js

@@ -0,0 +1,125 @@
+/**
+ * `about-notice` 子包宿主入口（P-F 第一格：`lib/components/about-notice/` → `packages/about-notice/`）。
+ *
+ * 为什么这一格先出：它那两条路由与主包其余路由**没有共享可变状态**（规模由
+ * `node test/tools/host-route-index.mjs` 现算），出户成本最低，而收益是宿主可以把
+ * `cordis.patch.yml` 里这一行单独 disable（其余各行一个不动）。
+ *
+ * 两处加载路径共用同一份实现（照抄 dsh-ops 的组件真形）：
+ *   ① 宿主把 patch 行的 `name` 当**独立 plugin** 加载 ⇒ `apply(ctx, config)` 是入口；
+ *   ② 门面的 `applyComponent(root, rawConfig, 'about-notice')` 是"按组件加载"入口。
+ * P-F 之后两条路径的 deps **不再是两份各写各的字面量**：门面与入口都从
+ * `lib/subpackage-boot.js` 的 `subpackageKeys('about-notice', ctx)` 取**同一份冻结键视图**
+ * ⇒ 两条路径不可能漂移（对账面 = `test/verify-inject-contracts.mjs` ② 的叶子冻结表逐键对账）。
+ *
+ * ⚠️ **跨包纪律（ADR-0014 S5.1 / S5.2，判据 `test/verify-subpackage-purity.mjs`）**：本模块
+ * **零主包说明符、零相对路径逃出本包** —— 只 import 本包内的路由族与 `node:` 内建。宿主能力一律
+ * 经 `ctx.wallpaperEngineHost` 的键视图（`host.keys('about-notice', ctx)`）取。这不是风格问题：
+ * 相对 import 主包文件、或 import 主包名，都是该判据的硬红。
+ *
+ * ⚠️ **取服务姿势**：`inject` 必须先声明（`webServer` + `wallpaperEngineHost`）再读
+ * `ctx.<服务>`。cordis 的 reflect `get` 对「未声明 inject 就取的服务属性」当场抛
+ * `cannot get property "webServer" without inject at applyImpl`（真机原文），随后的早退分支
+ * 永远执行不到（死代码），两条装载路径双双失败、该组件的路由全 404。声明后由 Loader 保证
+ * 「服务就绪才激活」，`applyImpl` 里的早退只兜「服务在、但路由表还没挂上」这一种情况。
+ * 对应判据：`test/verify-bundle-rows.mjs` ⑧（入口读的每个 `ctx.<服务>` 都必须在其 inject 里）。
+ *
+ * ⚠️ **teardown 得交两份（关掉再打开子组件会撞 `duplicate … route`）**：本模块导出的 `apply`
+ * 是**函数声明**（有 `prototype`）⇒ cordis 的 loader 走 `new apply(ctx, config)` 分支、
+ * **返回值被丢弃** ⇒ 只 `return keys.runComponent(…)` 的话 fiber 卸载时没人撤路由（旧注册留在
+ * 宿主路由表里），下一次启用立刻撞「重复路由」。所以返回值一律走 `keys.handOffTeardown(ctx, …)`：
+ * 同一份 disposer 也交给 `ctx.effect`（cordis 的显式清理通道）并做幂等包装。见 `lib/host-boot.js`。
+ *
+ * ⚠️ **模块作用域纪律（P2-1b 定，P-F 后仍适用）**：模块作用域（顶层、任何函数体之外）只许放
+ * 声明/常量 —— 不得在模块求值期去读别的模块的绑定并调用它（那一刻对方可能还没求值完，抛
+ * `ReferenceError: Cannot access '…' before initialization`，P2-1b NC1 实测报错原文）。
+ */
+import { join } from 'node:path';
+// 本包内的两条路由族（`lib/routes/*.js` 是路由族的**唯一**落点：落在别处 `docs/ROUTE-INDEX.md`
+// 会静默少行，见 test/tools/host-route-index.mjs 的候选面）。
+import { registerGithubStarsRoutes } from './routes/github-stars.js';
+import { registerAboutQrRoutes } from './routes/about-qr.js';
+
+/** patch 行 slug（`cordis.patch.yml` 里该行 `name` 的完整值，两处逐字相等）。 */
+export const name = 'dsh-plugin-folia-about-notice';
+
+/**
+ * 硬依赖 web 服务 + 主包宿主服务：与主行 `lib/index.js` 的 `inject` 同一套语义。
+ * 组件行走 patch 行加载时，Loader 靠这两句保证「服务就绪才激活」，`ctx.webServer` /
+ * `ctx.wallpaperEngineHost` 才读得到。
+ */
+export const inject = ['webServer', 'wallpaperEngineHost'];
+
+/** 独立 plugin 入口：宿主按 patch 行加载本子包时走这里，转调本模块的实现（不经门面）。 */
+export function apply(ctx, config) {
+  // ⚠️ 这个字面形态是**承重**的：`test/verify-inject-contracts.mjs` 的 `tableBindingNames()` 按
+  // `const <host> = ctx.<服务名>` 认「本文件里的冻结表绑定」（`recvRe`），再据此把下面调用点的
+  // `...keys` 展开成叶子冻结表。写成 `ctx && ctx.<服务名>` 守卫就认不出表 ⇒ 整包调用点判 dynamic
+  // 而红（nc-sub7 钉的就是这条：接收者必须源自 `ctx.<服务名>`）。
+  const host = ctx.wallpaperEngineHost;
+  // 拿不到服务名就大声失败：静默 `undefined` 会让下面每一步都在 undefined 上取属性（半死态）。
+  if (!host) {
+    throw new Error('[folia] about-notice 没拿到 wallpaperEngineHost 服务'
+      + '（inject 声明与宿主装载顺序不匹配）');
+  }
+  // 键视图 = `lib/subpackage-boot.js` 的 SUBPACKAGE_KEY_TABLE 里本包那一行（值全部来自主包模块级绑定）。
+  // 记账 / 错误留证 / 「失败仍原样抛」三件事都在 `keys.runComponent()`（门面 `applyComponent`
+  // 走的是同一个函数）⇒ 两条装载路径共用一份语义，不可能一条记了、另一条忘了。
+  const keys = host.keys('about-notice', ctx);
+  // `http` 面（`sendJson` / `bodyReader`）不在冻结键表里，与 `packages/fonts` 同款：按需显式带上。
+  const deps = Object.freeze({ ...keys, http: host.http });
+  return keys.handOffTeardown(ctx, keys.runComponent('about-notice', ctx, config, deps, applyImpl));
+}
+
+/**
+ * 组件实现。第三个形参名取 `c`（与 `lib/kernel/host-session.js` 同一约定）：
+ * `test/tools/host-route-index.mjs --deps` 按 `const { … } = c;` 现抽契约；路由族调用点的
+ * `...keys` 展开则由 `test/verify-inject-contracts.mjs` 按冻结表认（`keys` 与 `apply()` 里那个
+ * 绑定同名 ⇒ 两边指的是同一份键视图）。
+ */
+export function applyImpl(root, _rawConfig, c) {
+  const keys = c;
+  const { base, pluginName, repoSlugFromPkg, pluginDataDir, componentViewFrom, createComponentSession } = c;
+  // 两条装载路径都能这么读：① 组件行自己声明了 `inject = ['webServer', 'wallpaperEngineHost']`；② 门面路径的 `root`
+  // 就是门面的 ctx，而门面同样声明了 `inject = ['webServer']`（主行 `lib/index.js` 的 `inject` 声明）。
+  const webServer = root && root.webServer;
+  // 与门面 `apply()` 同款早退：服务在、但 register 面还没挂上（或换成了别的 webServer 实现）。
+  if (!webServer || typeof webServer.register !== 'function') return () => {};
+
+  // P2-7B 注入面收窄：从内核取**本组件声明的视图**（`COMPONENT_VIEW_KEYS['about-notice']`），
+  // 不再从整个 `hostKernel` 现解构 —— 后者等于把整个内核（键数与分级由
+  // `test/verify-component-face.mjs` 现算）当成注入面（M9 的现状）。视图缺键即抛，不静默 `undefined`。
+  const view = componentViewFrom('about-notice');
+  // 迷你会话（disposers / activeStreams / mediaMap / log / serveFile / 同序 teardown）收在内核侧；
+  // serve 套件的入参（`SESSION_SERVE_KEYS`：appendDiagLine / traceRequests / traceMediaRequests /
+  // readWebShim / buildSeedScript）由会话从视图取 ⇒ 它们不再出现在组件入口的解构面里。
+  const { log, disposers, serveFile, teardown } = createComponentSession(root, { base, pluginName }, view);
+  const { ABOUT_DIR } = view;
+
+  // ⚠️ **注册期必须包 try**（P2-4）：本实现要注册**两条**路由族，第 N 条抛错时前面 N-1 条已经
+  // 把 disposer 推进了 `disposers`。若不在这里收尾就往外抛，`teardown` 就**永远不会交回宿主**
+  // （`runComponent()` 只在 impl 正常返回时拿到它）⇒ 已注册的路由留在宿主路由表里，下一次启用
+  // 立刻撞 `webserver: duplicate … route`。收尾失败不掩盖原始错误：teardown 自己吞异常，
+  // 原错照抛（装载失败必须仍然是红的）。
+  try {
+    // 「关于」页签的仓库 star 数 → lib/routes/github-stars.js。**只读**一条腿：本插件唯一一处
+    // 出站请求（api.github.com），带 10 分钟 TTL + 落盘缓存兜底；一键 star 不做（GitHub 要点星
+    // 必须有用户凭据，插件不存任何 token）。
+    registerGithubStarsRoutes(webServer, {
+      ...keys, disposers, base, repoSlug: repoSlugFromPkg(),
+      cachePath: () => join(pluginDataDir(), 'star-count.json'),
+      log, http: keys.http,
+    });
+
+    // 「关于」页签的两张联系方式二维码（静态 PNG，白名单直出）→ lib/routes/about-qr.js。
+    registerAboutQrRoutes(webServer, { ...keys, disposers, base, aboutDir: ABOUT_DIR, serveFile });
+  } catch (error) {
+    teardown();
+    throw error;
+  }
+
+  // 本组件自己的收尾（会话的 teardown，见 lib/kernel/component-session.js）：与 host-session 的
+  // teardown 同序（逐个 disposer → destroy 在途流 → 清两个容器），但**没有** releaseKernelLease
+  // —— 见文件头那条有意不对称。
+  return teardown;
+}

package/lib/components/about-notice/routes/about-qr.js

@@ -0,0 +1,92 @@
+/**
+ * packages/about-notice/lib/routes/about-qr.js — 「关于」页签那两张联系方式二维码 + 「更新公告」配图的**静态资源路由**：
+ * `GET/HEAD <BASE>/about-qr/<文件名>`（`lib/about/` 下的 PNG/JPEG，白名单里没有的一律 404）。
+ * 公告配图（`update-notice.jpg`）与二维码同走这一族：同为随包静态图、同为"会换"的图
+ * （群号换了就得换码、公告配图随版本换图），URL 段沿用 `/about-qr/` 前缀 —— 本文件头注释
+ * 就是口径，改名反而会 churn 两处稳定 URL。
+ *
+ * 为什么单独成文件：这是全插件**唯一一处"把随包文件按 URL 直出"**的资源族（其余静态面要么是
+ * 用户数据 `/media`，要么是渲染页 `/scene-live`），而"URL 段怎么变成路径"必须能在一处读完 ——
+ * 这段代码离用户输入最近。
+ *
+ * 契约：`registerAboutQrRoutes(webServer, c)`；`c` 里是这一族用到但不属于它的东西：
+ *   · `disposers` / `base: BASE`  ← 清理句柄与路径前缀
+ *   · `aboutDir`                  ← `lib/about/` 的绝对路径（包内资源，只读）
+ *   · `serveFile`                 ← 出字节的统一出口（mime / Range / 条件 GET 都在它手里）
+ *
+ * 不变量（每条都有守卫）：
+ *   · **路径只能来自白名单**：URL 段**不做**任何拼接 —— 先用 `decodeURIComponent` 取到名字，
+ *     再在 `aboutQrFile(name)` 里**查表**换路径。没进表的名字连 `join()` 都不会被调用，
+ *     于是 `..`、绝对路径、NUL、编码穿越在结构上就不可能落到白名单之外（第二道是
+ *     `serveFile` 前的存在性判断）。
+ *   · **只认 GET/HEAD**：其余方法 405（本路由没有写面）。
+ *   · **304 由 serveFile 负责**：`revalidate` 让应答带 ETag(`size-mtime`) + `no-cache`，
+ *     换掉 `lib/about/` 里的 PNG 后客户端**立刻**拿到新图（这是一张会变的图：群号换了就得换码）。
+ *   · **错误响应不带缓存**（`serveFile` 的既有口径）：Electron 缓存过 404 之后即使文件到位
+ *     也会一直显示旧的错误页。
+ */
+
+import { resolve, relative, isAbsolute } from 'node:path';
+
+/**
+ * 白名单：URL 段 → 文件名。**唯一**把请求映射到磁盘的地方。
+ * 名字用 `String` 的精确比较（`===`），不看前缀/后缀 —— 于是 `qq-group.png.bak`、
+ * `./qq-group.png`、`qq-group.png/` 之类都过不了。
+ */
+const ABOUT_QR_FILES = ['qq-group.png', 'douyin-group.png', 'update-notice.jpg'];
+
+/**
+ * 命中白名单返回绝对路径（含目录包含性复查），否则 null。
+ * ⚠️ **不导出**：路由族模块（`lib/routes/*.js` 或组件目录里的实现文件）里每个导出函数都会被
+ * 路由索引当成一个"注册入口"去解析 context 契约（多导一个普通函数会让那条判据误红）——
+ * 这条规则由 `verify-route-index` 钉住。
+ * 要测它就走路由（穿越 / 编码 / 未登记名字一律 404）。
+ */
+function aboutQrFile(name, aboutDir) {
+  const hit = ABOUT_QR_FILES.find((f) => f === String(name));
+  if (!hit) return null;
+  const dir = resolve(aboutDir);
+  const abs = resolve(dir, hit);
+  // 第二道（对将来的白名单维护者）：文件名必须是该目录的**直接子项**。
+  // 现在这张表里不可能有 `..`，但表是人维护的 —— 判据不依赖"人不犯错"。
+  //
+  // ⚠️ 判据必须**分隔符无关**：`relative()`，不是 `abs.startsWith(dir + '/')`。
+  // **实测（CI windows-latest）**：前缀写法在 Windows 上必然判 null ——
+  // `resolve()` 产出的是反斜杠路径，而前缀拼的是正斜杠 ⇒ 连白名单命中的图都 404
+  // （本机 macOS 全绿、CI 红，症状就是这个）。
+  // 这条判据与 lib/routes/fontsets.js 的 `insideDir`、lib/upload-store.js 的 `resolveUploadFile`
+  // **逐字同一条**。
+  const rel = relative(dir, abs);
+  return rel && !rel.startsWith('..') && !isAbsolute(rel) ? abs : null;
+}
+
+/** 注入契约（P2-7A / ADR-0013 D12）：本族从 `c` 消费的**必需**键 —— 门面/组件行调用点必须逐键给到（判据 test/verify-inject-contracts.mjs 双向对账）。 */
+export const DEPS = ['disposers', 'base', 'aboutDir', 'serveFile'];
+
+export function registerAboutQrRoutes(webServer, c) {
+  const { disposers, base: BASE, aboutDir, serveFile } = c;
+
+  disposers.push(webServer.register({
+    kind: 'prefix',
+    path: `${BASE}/about-qr`,
+    handler: (req, res) => {
+      const method = (req.method || 'GET').toUpperCase();
+      if (method !== 'GET' && method !== 'HEAD') { res.statusCode = 405; res.end(); return; }
+      const headOnly = method === 'HEAD';
+      // `new URL` 会先把 `..` / `%2e%2e` / 反斜杠形式的点段规范化掉（WHATWG 语义），
+      // 能走到这里的只剩"看起来像文件名"的段；随后还要过白名单。
+      let url;
+      try { url = new URL(req.url || '/', 'http://x'); } catch { res.statusCode = 400; res.end('bad url'); return; }
+      const rest = url.pathname.slice(`${BASE}/about-qr`.length).replace(/^\/+/, '');
+      if (!rest || rest.includes('/')) { res.statusCode = 404; res.end('not found'); return; }
+      let name;
+      try { name = decodeURIComponent(rest); } catch { res.statusCode = 400; res.end('bad encoding'); return; }
+      const abs = aboutQrFile(name, aboutDir);
+      if (!abs) { res.statusCode = 404; res.setHeader('Cache-Control', 'no-store'); res.end('not found'); return; }
+      // revalidate：尺寸/时间未变 ⇒ 304 无体；变了 ⇒ 立刻送新图（这些都是"会换"的图：
+      // 群号换了就得换码，公告配图随版本换）。serveFile 按**扩展名**给 mime —— 混排
+      // PNG/JPEG 不需要这里做任何事。
+      serveFile(abs, req, res, headOnly, { revalidate: true });
+    },
+  }));
+}

package/lib/components/about-notice/routes/github-stars.js

@@ -0,0 +1,143 @@
+/**
+ * packages/about-notice/lib/routes/github-stars.js — **仓库 star 数**的唯一一条路由：`GET <BASE>/star-count`
+ * （「关于」页签那行「⭐ 当前 N star」的数据源）。
+ *
+ * 为什么单独成文件：**这是本插件唯一一条出站请求**（其余部分全是本机数据）。"什么时候可以
+ * 联网 / 拉不到怎么办 / 缓存放哪 / 会不会被限流"必须能在一处读完 —— 写进 `lib/index.js` 只会
+ * 让那个门面再多一段与它无关的联网逻辑。
+ *
+ * 为什么不做"一键 star"：GitHub 不允许未认证的程序点星（`PUT /user/starred/…` 要用户凭据）。
+ * 插件**不存任何 token**、也不借用本机 `gh` 的凭据 ⇒ 这里只有**只读**一条腿，点星由用户
+ * 在仓库页完成（关于页给的是链接 + 可复制地址）。
+ *
+ * 契约：`registerGithubStarsRoutes(webServer, c)`；`c` 里是这一族用到但不属于它的东西：
+ *   · `disposers` / `base: BASE`  ← 清理句柄与路径前缀
+ *   · `repoSlug`                  ← 'owner/repo'（`lib/host-boot.js` 从 package.json 现读，
+ *                                    见那里的 `repoSlugFromPkg` —— 仓库地址只有一处真源）
+ *   · `cachePath()`               ← 落盘缓存路径（`pluginDataDir()/star-count.json`）
+ *   · `fetchJson(url, ms)`        ← **可注入**的出站请求（守卫喂替身，避免测试联网）
+ *   · `log`                       ← 失败留痕（成功不记：成功是常态，不该刷屏）
+ *
+ * 不变量（每条都有守卫）：
+ *   · **只读**：只 GET `api.github.com/repos/<slug>`，永不发写请求、永不带凭据。
+ *   · **绝不把失败当错误甩给用户**：网络失败 / 非 2xx / 限流都回 200 + `ok:false` + 原因；
+ *     有落盘缓存时回它并标 `stale:true` —— 关于页显示"上一次取到的值"，不是断网图标。
+ *   · **不放大请求**：TTL（10 分钟）内直接回内存缓存；并发请求合并成一次出站（GitHub 未认证
+ *     限流是 **60 次/小时/IP**，且**整机共享** —— 别的程序也在用这个额度）。
+ *   · **失败要重试、成功才计 TTL**：失败不写 `at`（下次一问就再试），只有成功才进入冷却。
+ *   · **超时必须收**：出站 8s 超时（`AbortSignal.timeout`），不能让一个挂住的连接占住 handler。
+ *   · **落盘必须原子**：同目录 `.tmp` + rename（半截 JSON 会让"离线兜底"这条腿永久失效）。
+ */
+
+import { readFileSync, writeFileSync, renameSync } from 'node:fs';
+
+/** 成功结果的新鲜期：10 分钟内不再出站（客户端侧同一量级，两处相乘 ≈ 最坏 20 分钟一次）。 */
+const STAR_TTL_MS = 10 * 60 * 1000;
+/** 出站超时：GitHub 正常在 1s 内应答，8s 足够，也不会把设置页的一次打开拖长。 */
+const STAR_FETCH_TIMEOUT_MS = 8000;
+
+/** 默认出站实现：只读 GET，带 UA（GitHub API 要求有 UA），带超时。 */
+async function defaultFetchJson(url, ms) {
+  const res = await fetch(url, {
+    redirect: 'follow',
+    signal: AbortSignal.timeout(ms),
+    headers: {
+      'User-Agent': 'dsh-folia',
+      Accept: 'application/vnd.github+json',
+    },
+  });
+  if (!res.ok) {
+    throw new Error('HTTP ' + res.status);
+  }
+  return res.json();
+}
+
+/** 从 API 应答里取 star 数：形状不对就当失败（宁可显示"取不到"，也不要显示一个假的数）。 */
+function starsFromApi(json) {
+  const n = json && json.stargazers_count;
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+}
+
+/** 注入契约（P2-7A / ADR-0013 D12）：本族从 `c` 消费的**必需**键 —— 门面/组件行调用点必须逐键给到（判据 test/verify-inject-contracts.mjs 双向对账）。
+ *  `http` 是主包 json-response / http-body 的**唯一出口**（P-F：本族不再相对 import 主包文件）。 */
+export const DEPS = ['disposers', 'base', 'repoSlug', 'cachePath', 'log', 'http'];
+/** 允许缺席的键：真实调用点（组件行 about-notice）不传，缺省实现是下面的 `defaultFetchJson`。 */
+export const OPTIONAL_DEPS = ['fetchJson'];
+
+export function registerGithubStarsRoutes(webServer, c) {
+  const { disposers, base: BASE, repoSlug, cachePath, log, http } = c;
+  const fetchJson = typeof c.fetchJson === 'function' ? c.fetchJson : defaultFetchJson;
+
+  /** 内存缓存 { count, at } —— 进程内共享，重启后由落盘那份接上。 */
+  let mem = null;
+  /** 在途请求：并发合并（多个窗口同时打开设置页也只出站一次）。 */
+  let inflight = null;
+
+  const fresh = (v) => Boolean(v) && Number.isFinite(v.count) && Date.now() - Number(v.at || 0) < STAR_TTL_MS;
+
+  function readDisk() {
+    try {
+      const o = JSON.parse(readFileSync(cachePath(), 'utf8'));
+      if (o && Number.isFinite(o.count) && Number.isFinite(o.at)) return { count: o.count, at: o.at };
+    } catch { /* 没有 / 读不懂都当"没有" —— 缓存不是真源 */ }
+    return null;
+  }
+
+  function writeDisk(v) {
+    try {
+      const file = cachePath();
+      const tmp = file + '.tmp';
+      writeFileSync(tmp, JSON.stringify({ count: v.count, at: v.at }));
+      renameSync(tmp, file);
+    } catch (err) {
+      // 写不进缓存不影响这次应答；留个痕就够（下次仍能联网取到）。
+      try { log('star-count 缓存写入失败：' + (err && err.message ? err.message : err)); } catch { /* ignore */ }
+    }
+  }
+
+  async function fetchOnce() {
+    const url = 'https://api.github.com/repos/' + repoSlug;
+    const json = await fetchJson(url, STAR_FETCH_TIMEOUT_MS);
+    const count = starsFromApi(json);
+    if (count === null) throw new Error('unexpected payload');
+    const got = { count, at: Date.now() };
+    mem = got;
+    writeDisk(got);
+    return got;
+  }
+
+  disposers.push(webServer.register({
+    kind: 'exact',
+    path: `${BASE}/star-count`,
+    handler: async (req, res) => {
+      // 薄别名：保留调用点写法（只有 200 + body），实现收敛到主包的 lib/json-response.js（经
+      // 宿主服务的 `http` 面注入 —— P-F 起本包不再相对 import 主包文件）。
+      // 缓存由**本路由**管（TTL 在上游），别让浏览器/CDN 再叠一层不可控的缓存 ⇒ no-store。
+      const reply = (body) => http.sendJson(res, 200, body);
+      if ((req.method || 'GET').toUpperCase() !== 'GET') { res.statusCode = 405; res.end(); return; }
+      // 没有可解析的仓库地址（package.json 被改坏 / 不是从包安装）：功能关闭，但**不报错** ——
+      // 关于页只是不显示数字，其余照常。
+      if (!repoSlug) { reply({ ok: false, count: null, error: 'no-repo' }); return; }
+
+      const cached = mem || readDisk();
+      if (fresh(cached)) {
+        mem = cached;
+        reply({ ok: true, count: cached.count, fetchedAt: cached.at, stale: false });
+        return;
+      }
+      try {
+        if (!inflight) {
+          inflight = fetchOnce().finally(() => { inflight = null; });
+        }
+        const got = await inflight;
+        reply({ ok: true, count: got.count, fetchedAt: got.at, stale: false });
+      } catch (err) {
+        const stale = cached || readDisk();
+        try { log('star-count 拉取失败：' + (err && err.message ? err.message : err)); } catch { /* ignore */ }
+        // 有旧值就回旧值（标 stale）：关于页显示"上一次取到的数"比显示"取不到"有用。
+        if (stale) reply({ ok: true, count: stale.count, fetchedAt: stale.at, stale: true });
+        else reply({ ok: false, count: null, error: String((err && err.message) || err) });
+      }
+    },
+  }));
+}

package/lib/components/fonts/client.build.json

@@ -0,0 +1,22 @@
+{
+  "entry": "src/client.js",
+  "artifact": "lib/client.fonts.js",
+  "inline": [
+    {
+      "file": "src/appearance-font-section.js",
+      "why": "外观页签第六节「全局字体」的渲染器（原 src/panel-tabs-appearance.js:54-420，逐字搬来）；入口的 registerPanelSection 把它的 render 登记进面板节注册表",
+      "markers": [
+        "function familyOptions(sel, opts) {",
+        "function renderAppearanceFontSection(ctx) {"
+      ]
+    },
+    {
+      "file": "src/fontset-editor.js",
+      "why": "「字体集」编辑器面板（原 src/fontset-editor.js，整文件逐字搬来）：纯渲染 + 意图回调，由字体节的 renderFontSet(fontSet) 调用",
+      "markers": [
+        "function deleteLabel(row) {",
+        "function renderFontSetEditor(ctx) {"
+      ]
+    }
+  ]
+}

package/lib/components/fonts/index.js

@@ -0,0 +1,129 @@
+/**
+ * index.js — **字体系统子包的宿主入口**。
+ *
+ * 落点 = 字体子包的**宿主半边**（ADR-0014 S3.4）：
+ *   · 搬进来的：字体系统的**两条宿主路由族** —— `fontsets`（字体集 /fontsets）与
+ *     `system-fonts`（本机字体清单 /system-fonts），见 ./routes/*.js。
+ *   · P-C（2026-10-16）之后**浏览器半边也随包走**：入口 `src/client.js` + 外观页签第六节
+ *     「全局字体」渲染器 `src/appearance-font-section.js` + 字体集编辑器 `src/fontset-editor.js`，
+ *     产物 `lib/client.fonts.js` ⇒ 本包**声明** `dsh.client` 且清单里有 `exports['./client']`
+ *     （ADR-0014 S3.4 的两向判据）。
+ *   · **仍然不搬**：`src/fontset-store.js`、`src/system-fonts.js`、`src/font/apply.js`、
+ *     `src/font/typography.js`、`src/font/color-roles.js`、`src/font/components.js`
+ *     （它们与主包其它半边在求值期/运行期双向耦合，见 §6.1 = A 的归属裁决）。
+ *
+ * ⚠️ 归属（务必先读）：用户口径 **§6.1 = A「代码归属，不是状态归属」**（正本 = ADR-0013 **D20**）。
+ *    字体键的**真源与状态**在主包 `lib/settings-schema.js`（`FONTSET_KEYS` 单点定义）与
+ *    `fontsets/<id>.json`；本包裹走的只是**渲染器与描述符** ⇒ 本包**不持键、不持久化、
+ *    不注册 `settings.section`**，读值一律经主包构造的渲染 ctx（或本文件声明的 `host` 面）。
+ *
+ * 两条加载路径共用这一个实现（与 packages/about-notice/lib/index.js 同形）：
+ *   ① 宿主按 patch 行（cordis.patch.yml）当独立 plugin 加载 ⇒ `apply(ctx, config)`（拆出后**唯一**
+ *      的加载路径：主包门面已不再有字体路由的调用点）。
+ *   ② 两条路由族自己的 `registerXxxRoutes(webServer, c)` 也可以被别的调用点直接驱动 —— `c` 由本文件拼齐。
+ *
+ * ══ 跨包通道（唯一一条）══════════════════════════════════════════════════════════════
+ * ADR-0014 S5.1 / S5.3：子包宿主半边**不 import 主包任何模块**
+ * （相对路径 import 与主包裸 specifier 都禁止）。本包的 `inject` 声明主包供给的 Cordis 服务
+ * `wallpaperEngineHost`，`apply()` 里 `const host = ctx.wallpaperEngineHost` 取到全部面：
+ *   · `host.keys('fonts', ctx)` —— **冻结的显式键集**（本文件只消费它，不自己拼内核）；
+ *     缺 id / 缺键一律**抛错**，不许静默 undefined（ADR-0013 D3③「宁可显示、不可静默消失」的宿主侧纪律）。
+ *   · `host.keyNames('fonts')` —— 声明面（守卫读的那份；本文件拿它当 REQUIRED_KEYS 的对账面）。
+ *   · `host.handOff(ctx, dispose)` —— 与 lib/host-boot.js 同名函数同义：`export function apply`
+ *     是**函数声明**（有 prototype）⇒ cordis 走 `new apply(ctx)`、**返回值被丢弃** ⇒ 只 `return dispose`
+ *     不够，必须同时交 `ctx.effect`（同 lib/index.js 的 `apply()` 末尾 fiber disposer 教训 / lib/host-boot.js 的 `handOffTeardown`）。
+ *   · `host.schema` / `host.http` —— 共享内核的纯符号与 JSON 应答 / 读体的两个纯函数面；
+ *     两条路由族不再静态 import 主包，由本文件显式传给它们的 register（见 routes/*.js 文件头）。
+ *
+ * 为什么不是「解构整个 hostKernel」/ 不是叶子 import：`import` 是**模块图**上的边，关掉主包后子包
+ * 仍握着旧代 exports（ADR-0014 S5.1 / S5.3 反模式：留着指向主包的模块图边）；`inject` 才是 cordis 唯一的级联判据
+ * （`name in fiber.inject`）⇒ 主包停用，子包 fiber 自动 park（ADR-0014 S7.2「关主包 = 关整族」的物理基础）。
+ *
+ * 开发期解析：`scripts/dev-link-subpackages.mjs` 在 `<profile>/node_modules/` 建
+ * `dsh-plugin-folia-<pkg> → packages/<pkg>` junction（发布态天然是兄弟目录，同一份 patch 两态成立）。
+ * ⚠️ 本文件已零主包 specifier ⇒ 仓内跑它**不再**需要仓库根的 `node_modules/dsh-plugin-folia`
+ * 自链接（那一层链接只服务旧的 `dsh-plugin-folia/subpackage-boot.js` 叶子通道）。
+ */
+
+import { join } from 'node:path';
+
+import { registerFontsetsRoutes } from './routes/fontsets.js';
+import { registerSystemFontsRoutes } from './routes/system-fonts.js';
+
+/** 行标识：与 packages/fonts/cordis.patch.yml 里那行的 `name` 逐字相同（ADR-0014 S4.2 会逐字对账）。 */
+export const name = 'dsh-plugin-folia-fonts';
+
+/** 这一族的宿主注入面：`webServer`（两条路由都注册在它上面）+ 主包的跨包服务面（ADR-0014 S5.1）。 */
+export const inject = ['webServer', 'wallpaperEngineHost'];
+
+/**
+ * 宿主半边入口。`ctx` 是 cordis 的插件上下文（`new apply(ctx)` 形态），`config` 来自 patch 行的 config
+ * （本包今天不使用：路由路径/键名都是定死的，要求行为零回归）。
+ *
+ * @returns {() => void} 拆卸函数（同时已交 `ctx.effect`；mock ctx 无 effect 时退回返回值，见 host-boot.js:188-197）。
+ */
+export function apply(ctx, _config) {
+  const webServer = ctx && ctx.webServer;
+  // provider 缺席（主包没起 / 没有 webServer）：与 about-notice 同口径 —— 静默退回空拆卸，
+  // 不抛异常炸掉整行（行级失败静默）。
+  if (!webServer || typeof webServer.register !== 'function') return () => {};
+
+  // 跨包服务面：键集 / 声明面 / 拆卸交接 / 纯符号面都从这**一个**服务取（子包半边零主包说明符）。
+  const host = ctx.wallpaperEngineHost;
+  // 显式键集：键表 **逐字派生**自主包服务面的冻结表（真源 lib/subpackage-boot.js），缺 id / 缺键在这里抛错
+  // （**不静默 undefined**）。键集只含 host-only 的**运行期实例**；共享内核的纯符号面走 host.schema /
+  // host.http，由下方传给两条路由的 register。
+  const keys = host.keys('fonts', ctx);
+  assertFontsKeys(host.keyNames('fonts'), keys);
+
+  // 拆卸句柄数组：照主包 lib/kernel/host-session.js:190/:257 的口径（一个数组、插入顺序、
+  // 逐条兜错），两条路由族的 register 都往它 push。
+  const disposers = [];
+  // 两个调用点各自给**自己那一族**的键集：`...keys` 是冻结表（唯一真源），`disposers` 是共用
+  // 拆卸句柄数组，`cachePath` 只给 system-fonts 一族（fontsets 不消费它 —— 别把不认识自己的键塞给它，
+  // test/verify-inject-contracts.mjs 的调用点对账会把它记成「多给」）；
+  // `schema` / `http` 是两条族共用的**纯符号面**（来自 host），显式传给各自的 register。
+  try {
+    registerFontsetsRoutes(webServer, { ...keys, disposers, schema: host.schema, http: host.http });
+    registerSystemFontsRoutes(webServer, {
+      ...keys,
+      disposers,
+      schema: host.schema,
+      http: host.http,
+      // 落盘缓存路径与主包同式（本文件 :94；出户前 = 主包 lib/index.js:383）：pluginDataDir()/system-fonts.json。
+      cachePath: () => join(keys.pluginDataDir(), 'system-fonts.json'),
+    });
+  } catch (error) {
+    // 半边起不来就整行回滚（不留半死态：第一条已经 push 的 disposer 先跑掉再抛）。
+    disposeAll(disposers);
+    throw error;
+  }
+
+  return host.handOff(ctx, () => disposeAll(disposers));
+}
+
+/**
+ * 本包从 `c` 消费的全部键。**不手写第二份清单**：逐字派生自主包服务面的冻结表
+ * （`host.keyNames('fonts')`）—— 冻结表是唯一真源（守卫读的声明面），派生保证两份永不漂移。
+ * `disposers`/`cachePath`/`schema`/`http` 由本文件自带，不在冻结表内。
+ *
+ * ADR-0013 D3③「宁可显示、不可静默消失」的宿主侧对应纪律：键集**缺一个就抛错**，绝不让 `undefined` 顺着
+ * `c` 流进路由（那时错误会变成"某个请求 500"或"某个下拉空着"，离根因很远）。
+ * 声明面与实际键集不一致 = 契约漂移，必须在这里炸而不是靠人记得。
+ */
+function assertFontsKeys(required, keys) {
+  const missing = required.filter((k) => keys[k] === undefined);
+  if (missing.length) {
+    throw new Error(`[folia-fonts] host.keys('fonts') 缺少声明面要求的键：${missing.join(', ')}`);
+  }
+}
+
+/**
+ * 逐条兜错的拆卸：**插入顺序**、单条抛错不影响其余（与 lib/kernel/host-session.js:257 逐字同口径）。
+ * `splice(0)` 让重复调用成 no-op（teardown 可能被 ctx.effect + 调用方各跑一次）。
+ */
+function disposeAll(disposers) {
+  for (const d of disposers.splice(0)) {
+    try { d(); } catch { /* ignore */ }
+  }
+}