@gavinc-cn/touchstone-dsh 0.2.0 → 0.4.0

package/dsh-plugin/lib/pack-closure.mjs

@@ -0,0 +1,291 @@
+/**
+ * 发包闭包计算 —— 「npm 包里必须有哪些文件」的**唯一一份**算法（零依赖，只用 `node:`）。
+ *
+ * 为什么要有它：`package.json` 的 `files` 是**白名单**，漏一条就是「发出去的包起不来」，
+ * 而漏的形态是静默的 —— 2026-10-15 实测 `@gavinc-cn/touchstone-dsh@0.1.1` 的 105 个文件里
+ * **没有 `backend/routes/` 的 11 个文件**（白名单只写了 `backend/server.js` / `backend/lib` /
+ * `backend/schema`），解包后 `node backend/server.js` 当场
+ * `ERR_MODULE_NOT_FOUND: .../backend/routes/index.js`（`backend/server.js:61` 就 import 它）
+ * 并 exit 1。手写清单（`dsh-plugin/scripts/prepack-check.mjs` 的 `REQUIRED`）挡不住这种漏，
+ * 因为它只查「我记得的那些」；这里改成**从入口正推**：包内必需 = 两个入口的**静态 import
+ * 闭包** + 运行时时按路径读的数据根。新增一个 `backend/routes/xxx.js` 而忘了改白名单 ⇒
+ * 闭包自动长大 ⇒ 判据变红。
+ *
+ * 两个入口（`package.json` 的 `main` + Node 后端入口，见 `dsh-plugin/lib/index.js:117-118`）:
+ *   - `dsh-plugin/lib/index.js` —— dsh 插件壳，宿主 `require`/`import` 的就是它；
+ *   - `backend/server.js`      —— 薄壳 spawn 的 Node 后端进程。
+ * 只解析**相对说明符**（`./` / `../`）：`node:*` 内建与裸包名不是包内文件，一律记为
+ * `unresolved` 供人看（不参与判据 —— 把裸包名当必需会把判据搞成假红）。
+ *
+ * 数据根（`RUNTIME_RESOURCES`）是**手写的**，条目都带「谁在哪一行读它」的证据；递归 import
+ * 扫描器看不到这些「按路径拼出来的读」，所以只能人工登记 —— 但每条都写清理由，不写「大概
+ * 需要」。注意 `backend/schema/fixtures/*` **不在**闭包里：它只被 `backend/test/db.test.mjs`、
+ * `tools/parity/db-run.mjs`、`tools/export_schema.py` 读（测试/量具），运行时没人读
+ * （实测 `grep -rn fixtures backend/lib backend/routes` 无命中）—— 别凭印象往里塞。
+ *
+ * 白名单展开（`expandFilesEntries`）按 npm 的 `files` 语义实现最小规则，行为经实测校准
+ * （`npm pack --dry-run --json`，见下），不是照文档猜的：
+ *   - 条目相对包根；`*` 不跨 `/`（实测 `files:["*.py","*.md"]` 只收根级的 a.py/top.md，
+ *     子目录 `sub/b.py` 不收 ⇒ **没有** matchBase 语义），`**` 跨目录；
+ *   - 条目指到目录 ⇒ 递归含其内容（`backend/lib`、`webui/dist-plugin` 都是这个形态）；
+ *   - `package.json` / `README*` / `LICENSE*`（含 `LICENCE*`）恒含。
+ * 有意**不**建模 `.gitignore`：本仓 `.gitignore` 里有 `webui/dist-plugin/`，但它照进包
+ * （实测 3 个文件都在）—— 说明显式 `files` 条目压过忽略规则。副作用写在文件末尾「已知缺口」。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** 包根（本文件在 `<包根>/dsh-plugin/lib/` 下, 上溯三级） */
+export const PKG_ROOT = path.dirname(path.dirname(path.dirname(fileURLToPath(import.meta.url))));
+
+/** 闭包的两个入口（相对包根，posix 分隔） */
+export const ENTRIES = Object.freeze([
+  'dsh-plugin/lib/index.js',
+  'backend/server.js',
+]);
+
+/**
+ * 运行时时**按路径读**的数据根（静态扫描看不到；每条都要有证据行号）。
+ * `files` 列出「精确文件」（测试夹具不算，别往里塞）；`dirs` 列出「整个目录都要」——
+ * 目录内容在判据里**当场递归枚举**，所以往里新增数据文件也自动进入闭包。
+ */
+export const RUNTIME_RESOURCES = Object.freeze({
+  files: Object.freeze([
+    { rel: 'backend/schema/schema.sql', why: 'backend/lib/db.js:59 initDb 启动即读（目标 DDL）' },
+    { rel: 'backend/schema/schema.json', why: 'backend/lib/db.js:60 收敛器按它补列/建索引' },
+    { rel: 'backend/schema/migrations.json', why: 'backend/lib/db.js:61 声明式迁移清单，启动即执行' },
+  ]),
+  dirs: Object.freeze([
+    { rel: 'builtin_prompts/free_style', why: 'backend/lib/prompts.js:237 _ASSET_DIR，运行时读流程文档与文件模板' },
+    { rel: 'extensions', why: 'backend/lib/builtin-assets.js:262 DEFAULT_EXT_DIR，资产清单扫描根（routes/assets.js 的端点）' },
+    { rel: 'webui/dist-plugin', why: 'server 静态服务目录（薄壳启动参数 --web-dir 传的就是它，dsh-plugin/lib/index.js）' },
+  ]),
+});
+
+/** 目录递归枚举时跳过的东西（不进包，也不需要进闭包） */
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.run', '__pycache__']);
+
+/** 相对说明符扫描（见文件头：锚在行首，避开注释里的散文；多行 import 靠 `[^'"]` 跨行） */
+const IMPORT_FROM_RE = /^[ \t]*import\s+[^'"]*?\bfrom\s*['"]([^'"]+)['"]/gm;
+const IMPORT_SIDE_EFFECT_RE = /^[ \t]*import\s*['"]([^'"]+)['"]/gm;
+const EXPORT_FROM_RE = /^[ \t]*export\s+(?:\*|\{[^}]*\})\s*from\s*['"]([^'"]+)['"]/gm;
+const DYNAMIC_IMPORT_RE = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+/** posix 化（判据字符串一律用 `/`，Windows 上跑出来的也必须一样） */
+export function toPosix(rel) {
+  return rel.split(path.sep).join('/');
+}
+
+/** 目录清单缓存：同一进程内按 root 复用（判据是只读的静态检查，进程内不假设文件树会变） */
+const LIST_CACHE = new Map();
+
+/** 递归列出 root 下所有**文件**（相对包根，posix 分隔，排序）；结果按 root 缓存 */
+export function listFiles(root = PKG_ROOT) {
+  const cached = LIST_CACHE.get(root);
+  if (cached) return cached;
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;                       // 读不动就当不存在（判据自己会报缺）
+    }
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        walk(abs);
+      } else if (entry.isFile()) {
+        out.push(toPosix(path.relative(root, abs)));
+      }
+    }
+  };
+  walk(root);
+  out.sort();
+  LIST_CACHE.set(root, out);
+  return out;
+}
+
+/** 抽一个源文件里的相对说明符（去重、保持出现顺序） */
+export function scanRelativeSpecifiers(source) {
+  const found = [];
+  const add = (spec) => {
+    if (!spec) return;
+    if (!spec.startsWith('./') && !spec.startsWith('../')) return;
+    if (!found.includes(spec)) found.push(spec);
+  };
+  for (const re of [IMPORT_FROM_RE, IMPORT_SIDE_EFFECT_RE, EXPORT_FROM_RE, DYNAMIC_IMPORT_RE]) {
+    re.lastIndex = 0;
+    for (const m of source.matchAll(re)) add(m[1]);
+  }
+  return found;
+}
+
+/**
+ * 解析相对说明符 → 包内文件（posix 相对路径）；解析不到返回 null。
+ * 支持无扩展名（补 `.js`、`/index.js`），与 Node 的 ESM 解析口径近似（本仓无扩展名导入）。
+ */
+export function resolveSpecifier(fromRel, spec, root = PKG_ROOT) {
+  const baseDir = path.posix.dirname(fromRel);
+  const joined = path.posix.normalize(path.posix.join(baseDir, spec));
+  const candidates = [joined, `${joined}.js`, `${joined}.mjs`, path.posix.join(joined, 'index.js')];
+  for (const rel of candidates) {
+    if (rel.startsWith('..')) continue;              // 跑出包根：不是包内文件
+    const abs = path.join(root, rel);
+    try {
+      if (fs.statSync(abs).isFile()) return rel;
+    } catch { /* 不存在的候选，继续试下一个 */ }
+  }
+  return null;
+}
+
+/**
+ * 计算运行时闭包：两个入口的静态 import 闭包 + `RUNTIME_RESOURCES`。
+ * @returns {{files: string[], unresolved: Array<{from: string, spec: string}>,
+ *            entries: string[], resources: string[]}}
+ *   `files` 排序去重；`unresolved` 是相对说明符解析不到（或裸包名/`node:`）的清单，
+ *   只报不用（避免把裸包名当必需导致假红）。
+ */
+export function computeClosure(root = PKG_ROOT) {
+  const files = new Set();
+  const unresolved = [];
+  const queue = [...ENTRIES];
+  const seen = new Set();
+  while (queue.length > 0) {
+    const rel = queue.shift();
+    if (seen.has(rel)) continue;
+    seen.add(rel);
+    const abs = path.join(root, rel);
+    let source;
+    try {
+      source = fs.readFileSync(abs, 'utf8');
+    } catch {
+      unresolved.push({ from: rel, spec: '(入口本身读不到)' });
+      continue;
+    }
+    files.add(rel);
+    for (const spec of scanRelativeSpecifiers(source)) {
+      const resolved = resolveSpecifier(rel, spec, root);
+      if (resolved === null) unresolved.push({ from: rel, spec });
+      else queue.push(resolved);
+    }
+  }
+  const resources = [];
+  for (const item of RUNTIME_RESOURCES.files) {
+    files.add(item.rel);
+    resources.push(item.rel);
+  }
+  for (const item of RUNTIME_RESOURCES.dirs) {
+    const abs = path.join(root, item.rel);
+    if (!fs.existsSync(abs)) { unresolved.push({ from: '(资源根)', spec: item.rel }); continue; }
+    for (const rel of listFiles(abs)) {
+      const full = `${item.rel}/${rel}`;
+      files.add(full);
+      resources.push(full);
+    }
+  }
+  return {
+    files: [...files].sort(),
+    unresolved,
+    entries: [...ENTRIES],
+    resources: resources.sort(),
+  };
+}
+
+/** glob → 正则（npm `files` 最小语义：`**` 跨 `/`，`*`/`?` 不跨 `/`） */
+function globToRegExp(pattern) {
+  let re = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === '*') {
+      if (pattern[i + 1] === '*') {
+        i++;
+        if (pattern[i + 1] === '/') { i++; re += '(?:.*/)?'; }   // `**/` 也匹配零层
+        else re += '.*';
+      } else {
+        re += '[^/]*';
+      }
+    } else if (ch === '?') {
+      re += '[^/]';
+    } else if ('\\^$.|+()[]{}'.includes(ch)) {
+      re += `\\${ch}`;
+    } else {
+      re += ch;
+    }
+  }
+  return new RegExp(`${re}$`);
+}
+
+/**
+ * npm 恒含的文件（`files` 白名单管不着）—— **只在包根**，实测校准过：
+ * `files:["a.txt"]` 时 `sub/README.md` / `sub/deep/LICENSE` 都不进包，
+ * 而根级 `package.json` 恒在。别把这条写成「任意层级的 README/LICENSE」（会假绿：
+ * 例如 `tests/README.md` 会被误判成包内 —— 实测它不在 105 个文件里）。
+ */
+function isAlwaysIncluded(rel) {
+  if (rel === 'package.json') return true;
+  if (rel.includes('/')) return false;
+  return /^(README|LICENSE|LICENCE)(\..*)?$/i.test(rel);
+}
+
+/**
+ * 展开 `files` 白名单 → 包内文件集合（最小 npm 语义，见文件头）。
+ * @param {string[]} entries package.json 的 files 数组
+ * @param {{root?: string, allFiles?: string[]}} [opts] 便于测试注入（负对照就在内存里换 entries）
+ * @returns {Set<string>} posix 相对路径集合
+ */
+export function expandFilesEntries(entries, opts = {}) {
+  const root = opts.root || PKG_ROOT;
+  const all = opts.allFiles || listFiles(root);
+  const packed = new Set();
+  for (const rel of all) if (isAlwaysIncluded(rel)) packed.add(rel);
+  for (const raw of entries) {
+    const entry = path.posix.normalize(String(raw).replace(/^\.\//, '').replace(/\/+$/, ''));
+    if (!entry || entry.startsWith('..')) continue;
+    const abs = path.join(root, entry);
+    let stat = null;
+    try { stat = fs.statSync(abs); } catch { /* 不存在：当 glob 处理 */ }
+    if (stat && stat.isDirectory()) {
+      for (const rel of listFiles(abs)) packed.add(`${entry}/${rel}`);
+      continue;
+    }
+    if (stat && stat.isFile()) { packed.add(entry); continue; }
+    const re = globToRegExp(entry);
+    for (const rel of all) if (re.test(rel)) packed.add(rel);
+  }
+  return packed;
+}
+
+/**
+ * 判据本体：闭包里但包内没有的文件（空数组 = 过）。
+ * @param {string[]} closureFiles `computeClosure().files`
+ * @param {Iterable<string>} packedFiles `expandFilesEntries(...)`
+ */
+export function findUnpacked(closureFiles, packedFiles) {
+  const packed = packedFiles instanceof Set ? packedFiles : new Set(packedFiles);
+  return closureFiles.filter((rel) => !packed.has(rel));
+}
+
+/**
+ * 读仓库 `package.json` 的 `files` 并跑完整判据（`prepack-check.mjs` 与单测共用）。
+ * @returns {{ok: boolean, missing: string[], closure: object, packedCount: number, files: string[]}}
+ */
+export function checkPackClosure(root = PKG_ROOT) {
+  const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  const entries = Array.isArray(pkg.files) ? pkg.files : [];
+  const closure = computeClosure(root);
+  const packed = expandFilesEntries(entries, { root });
+  const missing = findUnpacked(closure.files, packed);
+  return { ok: missing.length === 0, missing, closure, packedCount: packed.size, files: entries };
+}
+
+/**
+ * 已知缺口（写在这里，不装作没有）:
+ *   ① `.gitignore` / `.npmignore` 未建模 —— 若将来某个运行时文件恰好落在被忽略的目录里、
+ *      而白名单**没有**显式列出它，本判据会假绿（今天不会：闭包里的路径全部由显式条目覆盖）。
+ *   ② npm 的 `files` 对**符号链接**、`.npmrc`、`bundledDependencies` 有额外规则，本判据不管。
+ *   ③ 运行时**动态拼**出来的路径（例如按用户输入拼文件名）静态看不到，只能靠人工登记进
+ *      `RUNTIME_RESOURCES`；登记漏了就是假绿。
+ */

package/dsh-plugin/scripts/prepack-check.mjs

@@ -1,13 +1,20 @@
 /**
  * 发包前自检 —— package.json 的 `prepack` 钩子（`npm pack` / `npm publish` 前自动执行）。
  *
- * 两道检查:
+ * 三道检查:
  *  ① **必需文件在不在**：本包是自包含的（插件壳 + Python 平台 + 预构建 webui/dist-plugin +
  *     内置提示词/内置资产），少任何一块装到 profile 里都跑不起来；
  *  ② **三处「包名」逐字一致**：包根 package.json 的 `name`、`dsh-plugin/cordis.patch.yml`
  *     里 insert 行的 `name`、`dsh-plugin/lib/client.bundle.js` 里 `__ModuleLoader__.load({id})`
  *     的 id —— dsh 宿主按注册行的包名给浏览器半预留模块槽，三者不一致时页面报
  *     "loaded without registering"（2026-10-07 改名 @gavinc-cn/touchstone-dsh 时踩过）。
+ *  ③ **闭包 ⊆ 白名单**（2026-10-15 新增）：从两个入口（`backend/server.js`、
+ *     `dsh-plugin/lib/index.js`）正推运行时闭包（静态 import 图 + 运行时按路径读的数据根），
+ *     与 `files` 展开结果比对。①的手写清单挡不住「新加了一个文件、忘了改白名单」——
+ *     实测 0.1.1 发出去的包里 `backend/routes/` 11 个文件全缺，解包后
+ *     `node backend/server.js` 直接 ERR_MODULE_NOT_FOUND（`backend/server.js:61` import 它）。
+ *     算法在 `dsh-plugin/lib/pack-closure.mjs`（与 `tools/parity/test/pack-closure.test.mjs`
+ *     **同一份**，不是一个抄一个）；这里只读文件、**绝不递归调用 `npm pack`**（会被自己再触发）。
  *
  * 任一项不过就非 0 退出，让 `npm pack` / `npm publish` 直接中断：宁可发不出去，不可发出坏包。
  * 用法: node dsh-plugin/scripts/prepack-check.mjs
@@ -16,6 +23,8 @@ import { readFileSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { checkPackClosure } from '../lib/pack-closure.mjs';
+
 /** 包根（本脚本在 <包根>/dsh-plugin/scripts/ 下, 上溯三级） */
 const PKG_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 
@@ -24,6 +33,15 @@ const REQUIRED = [
   'package.json',
   'server.py',
   'requirements.txt',
+  // Node 后端骨架（2026-10-11 M0）：profile 里配 `backend: node` 时薄壳拉起的就是它，
+  // 缺了等于「开关一打开就起不来」——必须在发包自检里挡住。
+  'backend/server.js',
+  'backend/lib',
+  // 数据层共享契约（2026-10-11 M1）：`backend/lib/db.js` 启动即读 schema.sql /
+  // schema.json / migrations.json，缺了就是「Node 后端起不来」——同样必须在发包自检里挡住。
+  'backend/schema/schema.sql',
+  'backend/schema/schema.json',
+  'backend/schema/migrations.json',
   'builtin_prompts',
   'extensions/dsh-autocommit/asset.json',
   'webui/dist-plugin/index.html',
@@ -53,9 +71,19 @@ if (!bundle.includes(`id: ${JSON.stringify(pkg.name)}`)) {
 }
 if (pkg.private === true) failures.push('package.json 里 private: true, 发不出去（发布前删掉）');
 
+// 闭包 ⊆ 白名单: 从入口正推运行时必需文件, 逐条要求在 files 展开结果里
+// （算法见 dsh-plugin/lib/pack-closure.mjs；只读文件, 不跑 npm pack ⇒ 可以安全地待在 prepack 里）
+const closure = checkPackClosure(PKG_ROOT);
+if (!closure.ok) {
+  failures.push(`files 白名单漏了 ${closure.missing.length} 个运行时必需文件`
+    + `（新增运行时文件/目录后忘了改 package.json 的 files 就会这样）:`);
+  for (const rel of closure.missing) failures.push(`files 缺: ${rel}`);
+}
+
 if (failures.length > 0) {
   console.error(`prepack 自检未通过（${failures.length} 项）:`);
   for (const line of failures) console.error(`  - ${line}`);
   process.exit(1);
 }
-console.log(`prepack 自检通过: ${pkg.name}@${pkg.version}, ${REQUIRED.length} 个必需路径齐全, 包名三处一致`);
+console.log(`prepack 自检通过: ${pkg.name}@${pkg.version}, ${REQUIRED.length} 个必需路径齐全, 包名三处一致, `
+  + `运行时闭包 ${closure.closure.files.length} 个文件全在白名单内`);

package/dsh-plugin/src/client.js

@@ -272,10 +272,117 @@ function panelEntry() {
   return '/touchstone/app';
 }
 
-// 全屏面板: 无顶栏(iframe 吃满全屏) + 关闭按钮悬浮在左下角(位置与 dsh 侧栏入口一致)
+// ── 窗口装饰区让位(2026-10-17, 卡 987 方案 A) ─────────────────────────────────
+// 血案: 面板是全窗口浮层(position:fixed; inset:0), 而桌面版窗口的顶带(Windows 的最小化/
+// 最大化/关闭、macOS 的红绿灯)由桌面壳画在网页之上 —— 浮层顶部那行按钮正好落在它底下,
+// 在 dsh desktop 里整块被盖住、点不到(现象与取证见
+// doc_ai/debug_runtime/202610/20261017_0600_零项目首屏无可点建项目入口… .md)。
+// 修法: 让整个浮层从窗口顶边**下移**「壳实际绘制的窗口 chrome 高度」—— 顶带完整露给壳
+// (标题文字/拖拽区/窗口按钮都还在原位), 面板内容从它下面开始。等价于 dsh 自己主面板与
+// 弹窗的处理口径(layout 发布 --dsh-frame-top-clearance / --dsh-frame-chrome-top),
+// 而且**不需要 SPA 侧改任何代码**: iframe 拿到的视口自己就变矮了。
+// 高度来源(优先级从高到低; 全部读不到 ⇒ 0 ⇒ 独立浏览器形态, 行为与今天完全一致):
+//   ① dsh 桌面壳发布在 <html> 上的约定量(见 @deepseek-ai/dsh-client-ui-layout 的
+//      README「窗口 chrome 顶带」; 普通浏览器文档不发布这些值):
+//        --dsh-frame-chrome-top     壳当前**实际绘制**的顶带高(全屏时归 0)
+//        --dsh-frame-top-clearance  顶带之下的固定下沉量(Windows = 标题栏高, macOS = 48px)
+//      **取两者较大**: 全屏时 chrome-top 归零, 但 dsh 的 Frame 仍按 titlebar 高度让位,
+//      取 max 才能和主面板同口径、不会在全屏时又把窗口按钮盖回去。
+//   ② WCO 原生接口 navigator.windowControlsOverlay(Chromium/Electron; 旧桌面壳只开了
+//      overlay 但没发布 ① 的量时兜底): getTitlebarAreaRect() 的 y + height = 顶带高。
+//   ③ CSS env(titlebar-area-height) 探针(同一能力的老式访问面, 只支持 env 的壳兜底)。
+// 仍读不到(普通浏览器/不支持窗口浮层的壳) ⇒ 0 ⇒ 现状(独立形态本来就没有窗口装饰)。
+const CHROME_MAX_PX = 200; // 合法上限: 再大必然是脏值(标题栏不可能 200px), 一口拒绝
+
+/** 读 <html> 上某个 CSS 自定义属性的像素值。空串/无法解析/越界 ⇒ null（0px 是合法值）。 */
+function readChromePx(name) {
+  try {
+    if (typeof document === 'undefined' || !document.documentElement) return null;
+    const cs = window.getComputedStyle ? window.getComputedStyle(document.documentElement) : null;
+    if (!cs) return null;
+    const raw = cs.getPropertyValue(name);
+    if (!raw) return null;
+    const n = parseFloat(raw);
+    if (!Number.isFinite(n) || n < 0 || n > CHROME_MAX_PX) return null;
+    return n;
+  } catch { return null; } // 读样式异常绝不能拖垮面板本体
+}
+
+/** WCO 原生接口量顶带高(标题栏区域 rect 的 y + height); 不可见/不可用 ⇒ null。 */
+function wcoChromePx() {
+  try {
+    const nav = window.navigator;
+    const wco = nav && nav.windowControlsOverlay;
+    if (!wco || !wco.visible) return null;
+    const rect = wco.getTitlebarAreaRect ? wco.getTitlebarAreaRect() : null;
+    if (!rect) return null;
+    const n = (rect.y || 0) + rect.height;
+    if (!Number.isFinite(n) || n <= 0 || n > CHROME_MAX_PX) return null;
+    return n;
+  } catch { return null; }
+}
+
+/** env(titlebar-area-height) 探针: 挂一个 0 宽、高度取 env 的隐形探针量出来; 不支持 ⇒ null。
+ *  探针始终会被摘掉(成功/失败都摘), 不往宿主 DOM 里留垃圾。 */
+function envChromePx() {
+  try {
+    if (typeof document === 'undefined' || !document.body
+        || typeof document.createElement !== 'function'
+        || typeof document.body.appendChild !== 'function') return null;
+    const probe = document.createElement('div');
+    probe.style.cssText = 'position:fixed;left:0;top:0;width:0;'
+      + 'height:env(titlebar-area-height,0px);visibility:hidden;pointer-events:none';
+    document.body.appendChild(probe);
+    let h = 0;
+    try {
+      h = probe.getBoundingClientRect ? probe.getBoundingClientRect().height : 0;
+    } finally {
+      if (typeof probe.remove === 'function') probe.remove();
+      else if (typeof document.body.removeChild === 'function') document.body.removeChild(probe);
+    }
+    if (!Number.isFinite(h) || h <= 0 || h > CHROME_MAX_PX) return null;
+    return h;
+  } catch { return null; }
+}
+
+/** 窗口 chrome 顶带高(px): 面板浮层从窗口顶边下移这么多。0 = 没有桌面窗口装饰。 */
+function windowChromeTop() {
+  // ① dsh 桌面壳的约定量(两者取大, 口径见本节头注释)
+  const chrome = readChromePx('--dsh-frame-chrome-top');
+  const clearance = readChromePx('--dsh-frame-top-clearance');
+  if (chrome !== null || clearance !== null) {
+    return Math.max(chrome || 0, clearance || 0);
+  }
+  // ②③ 旧壳/其它壳兜底: WCO 原生接口 → env() 探针
+  return wcoChromePx() || envChromePx() || 0;
+}
+
+/** chrome 顶带高的响应式读取: 渲染期现读(首帧就带真值, 不闪一帧顶格),
+ *  壳换档(resize/进出全屏/窗口几何变化)时自增重渲染。 */
+function useWindowChromeTop() {
+  const [, setRevision] = React.useState(0);
+  React.useEffect(() => {
+    const bump = () => setRevision((n) => n + 1);
+    window.addEventListener('resize', bump);
+    document.addEventListener('fullscreenchange', bump);
+    // WCO 几何变化不是 DOM 事件(壳侧全屏/标题栏变高/贴边), 只能由原生接口通知
+    const wco = window.navigator && window.navigator.windowControlsOverlay;
+    if (wco && typeof wco.addEventListener === 'function') wco.addEventListener('geometrychange', bump);
+    return () => {
+      window.removeEventListener('resize', bump);
+      document.removeEventListener('fullscreenchange', bump);
+      if (wco && typeof wco.removeEventListener === 'function') wco.removeEventListener('geometrychange', bump);
+    };
+  }, []);
+  return windowChromeTop();
+}
+
+// 全屏面板: 浮层从窗口 chrome 顶带之下开始(没有桌面壳时 = 0 = 吃满全屏) +
+// 关闭按钮悬浮在左下角(位置与 dsh 侧栏入口一致)
 // iframe 同源, /touchstone/app 经薄壳反代到 server.py 的插件版 SPA
 function Panel() {
   const isOpen = useOpen();
+  const chromeTop = useWindowChromeTop(); // 窗口装饰顶带高: Windows 标题栏/macOS 红绿灯
   // 保活(2026-10-07): 打开过就在 DOM 里常驻, 关闭只把容器 display:none —— iframe 一旦
   // 从 DOM 摘掉, 内嵌 SPA 整篇文档就没了, 再打开是全新加载(路由/弹窗/滚动/未提交输入全丢)。
   // mounted 由「打开过」与「当前打开」合成: 首次打开的那一次渲染就带上 iframe(不等 effect
@@ -382,7 +489,9 @@ function Panel() {
   const visible = !zoneOk || shown; // 自动隐藏不可用时(zoneOk=false)保持常显
   return h('div', {
     style: {
-      position: 'fixed', inset: 0, zIndex: 9999,
+      // 顶边让出窗口装饰带(见 useWindowChromeTop): 桌面壳里 = 标题栏/红绿灯的高度,
+      // 普通浏览器里 = 0(与旧版 inset:0 完全一致)。其余三边照旧贴边。
+      position: 'fixed', top: chromeTop, left: 0, right: 0, bottom: 0, zIndex: 9999,
       background: 'var(--dsw-alias-bg-base, #161617)',
       display: isOpen ? 'block' : 'none', // 关闭 = 只隐藏: iframe 与内嵌 SPA 常驻(保活)
     },