@dsh-workbench/module-tools 0.2.10 → 0.2.11

package/README.md

@@ -22,14 +22,14 @@ dsh-wb-module publish               # 发货前的清单：门禁 + 三张表 +
 |---|---|
 | `contracts` | 模块契约：单元 id 唯一、两个面、四个脚本、`files`、peer 下限；以及**清单 ↔ 代码**（真正注册的工具）与**底稿 ↔ 清单**（`design.json` 的能力名）两处对账（见下） |
 | `protocol` | 模块声明协议：`dsh.workbench` 的 `apiVersion` 要在、静态半形状要对、不许有协议不认识的键（`scope` 现在**就是**不认识的键之一 —— 见下） |
-| `bundles` | 产物边界：宿主面里不许出现浏览器侧的东西 |
+| `bundles` | 产物边界：宿主面里不许出现浏览器侧的东西；浏览器产物里不许出现**内联的外壳 CSS**（模块从 `@dsh-workbench/shared` 根入口取运行期值就会这样） |
 | `source` | 源码边界：不直接引 dsh 的包、不引不是种子词的 `@deepseek-ai/*` |
 | `primitives` | dsh 原语只从模块表（`kit`）拿 |
 | `kit` | 这份外壳的 kit 成员到底有哪些（缺什么会当场点名） |
 | `cards` | 卡片渲染：五态都要画得出来，空数据不许抛 |
 | `standalone` | 独立构建：产物不依赖工坊里跑 |
 | `markers` | 公开包无内部标识（内网域名、企业内部名） |
-| `style` | 样式归属：模块不许定义外壳前缀（`wb-*`）的规则 |
+| `style` | 样式归属：模块不许定义外壳类（`wb-*`）的规则（判据看**复合选择器**，`:global(.wb-x)` 也算，只有同一个复合选择器里带模块自己的类才放行）；**裸 `<a>` 与裸交互控件（`<button>` / `<input>` / `<select>`）都判红** —— 前者用 kit 的 `Link`，后者用 `Button` / `TextField` / `SelectField` / `ChoiceGroup`；只有 `<textarea>` 与 `input[type=hidden\|file]` 例外（两处都没有那种形态） |
 | `alias` | 模块不指外壳：源码里没有指向外壳 `@/` 的引用 |
 
 三态输出：`✔ 通过` / `○ 不适用` / `✖ 不过`；有任何不过就退出 1。
@@ -103,7 +103,7 @@ dsh-wb-module design accept   # 用户逐条点头之后，把验收清单打勾
 | 模板 | 是什么 |
 |---|---|
 | `minimal`（默认） | 空壳：卡壳、文案、测试接好了，没有数据源 |
-| `diy` | 一份真能跑的样板：宿主侧一条只读路由真读盘、卡片五态、`?wbMock=1` 三档夹具，**三张表也是填好的** |
+| `diy` | 一份真能跑的样板：宿主侧一条只读路由真读盘、卡片五态，**三张表也是填好的** |
 
 `init` 会连模板里的 `*.tpl` 一起拷过去、把 `__UNIT__` / `__NAME__` / `__DESC__` 填上、剥掉 `.tpl` 后缀，
 再用 `design.json` 生成 README 那一段。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/module-tools",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "模块包的构建与门禁工具：build（单文件 ESM 宿主侧 + 套 loader 壳的浏览器侧）、check（契约/产物边界/源码边界/卡片渲染）。模块包不再各带一份构建脚本。",
   "license": "MIT",
   "type": "module",
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "esbuild": "^0.28.2",
-    "@dsh-workbench/shared": "0.2.10"
+    "@dsh-workbench/shared": "0.2.11"
   },
   "scripts": {
     "selfcheck": "node scripts/selfcheck.mjs"

package/src/checks/bundles.mjs

@@ -19,6 +19,7 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { inlinedShellRules } from '../css-shell.mjs';
 import { discoverModulePackages } from '../discover.mjs';
 
 const CLIENT_FORBIDDEN = [
@@ -63,6 +64,21 @@ export async function run() {
           );
         }
       }
+      // 外壳的组件样式**只有一份**（外壳注入那一次）。模块从 `@dsh-workbench/shared` 的**根入口**
+      // 取运行期值（`h` / `Fragment` / `useState` / 纯函数…）就会把整份组件 barrel 连 CSS 一起打进
+      // 自己的产物，注入后按顺序覆盖外壳那一份 —— 用户看到的是旧样式，而且外壳改了也不生效。
+      // 判断看复合选择器：`._hash_row.wb-iconButton` 这种「自己的类 + 外壳的槽类」是合规的，不算。
+      if (artifact.file === 'client.js') {
+        const inlined = inlinedShellRules(source);
+        if (inlined.length > 0) {
+          problems.push(
+            `${name}: ${artifact.what} ${artifact.file} 里内联了 ${inlined.length} 条外壳的 CSS 规则` +
+              `（${inlined.slice(0, 3).join(' · ')}）—— 外壳的组件样式只有一份：` +
+              'React 原语从 \'react\' 拿、外壳给的东西从 kit 拿（`@dsh-workbench/shared` 根入口是浏览器 barrel，' +
+              '它会急切地把 components/** 连样式一起拉进来）。见 ADR-0028 §5.1',
+          );
+        }
+      }
     }
   }
 
@@ -78,7 +94,7 @@ export async function run() {
   }
   return {
     status: 'pass',
-    notes: [`${checked} 份产物 · 浏览器侧无 node 内置 · 宿主侧无 DOM/react`],
+    notes: [`${checked} 份产物 · 浏览器侧无 node 内置 · 宿主侧无 DOM/react · 浏览器侧没有内联的外壳 CSS`],
     problems: [],
   };
 }

package/src/checks/cards.mjs

@@ -103,7 +103,7 @@ function fakeDshPackage() {
 function loadFace(clientFile) {
   let captured;
   const fakeWindow = {
-    // 浏览器里 `window.location` 永远在；缺了它，夹具模式的开关会先抛（第一次跑就踩到）。
+    // 浏览器里 `window.location` 永远在；缺了它，读它的客户端代码（含 `?wbMock=1` 那个开关）会先抛。
     location: { search: '', href: 'http://127.0.0.1:3081/' },
     __ModuleLoader__: {
       load: (entry) => {

package/src/checks/style.mjs

@@ -11,13 +11,54 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { shellRulesIn } from '../css-shell.mjs';
 import { discoverModulePackages } from '../discover.mjs';
 
-const SHELL_SELECTOR = /(^|[\s,>+~])\.wb-[a-z0-9-]+/;
-const RULE = /\.wb-[a-z0-9-]+[^{}]*\{/;
 // 外链一律走 kit 的 `Link`：它自带的样式（正文色 / hover 下划线 / 12px / 那个外链小箭头）是唯一一份。
 // 手写 `<a>` / `h('a', …)` 拿到的是浏览器默认样式，而且每个人写的都不一样（这正是"同一个东西样式不一样"的来源）。
 const BARE_ANCHOR = /(h\(\s*['"]a['"]|jsx\(\s*['"]a['"]|<a[\s>])/;
+
+// 交互控件同一条理由：按钮 / 单行输入 / 下拉在 kit 与 dsh 原语里都有对应形态
+// （`Button` · `TextField` · `SelectField` / `ChoiceGroup`），手写的那一份拿到的是浏览器默认样式 ——
+// 悬停、禁用、焦点环、色板、字号各写一遍，不跟主题也不跟语言。
+// 例外只有两个，都是"两处都没有的形态"：多行输入（`<textarea>`，dsh 与 kit 都没有）与
+// `input` 的 `type="hidden"` / `type="file"`（不是标准控件，拿不到样式）。这两个放行。
+const BARE_CONTROLS = [
+  { tag: 'button', what: '按钮', use: 'dsh 的 Button（variant / size），或 kit 的 SaveBar / BlockerState' },
+  { tag: 'input', what: '单行输入', use: 'kit 的 TextField' },
+  { tag: 'select', what: '下拉', use: 'kit 的 SelectField（搜索 / 分组 / 空态 / 加载态都自带）' },
+];
+const NATIVE_ONLY_INPUT = /type\s*[:=]\s*['"](?:hidden|file)['"]/;
+
+// 历史豁免：这三处是**已知**的手写控件，各有各的理由，跟着各自的迁移走 ——
+//   ① `module-cmdb/src/views/MenuField.tsx`（两处：那个下拉的触发钮与它的等待态）
+//      ＝ ADR-0051 §4 迁移清单里那两处：两件都归 `SelectField`（等待态就是它的 `loading`），
+//      但**要等外壳先发一版** —— 模块的 peer 下限得先有 `SelectField`，否则装上就崩。
+//   ② `module-cmdb/src/views/ChooseEnvsBody.tsx`（一处：`role="radio"` 那一列选项行）
+//      ＝ 对应 kit 的 `ChoiceGroup`；换不换是那个模块自己的一次改动（分组标题与标记是它的排版）。
+// 这是**棘轮**：迁完一处就删一行，别只加不减（名单长起来等于这条判据没有）。
+// 键是 `<包名>:<相对模块根的文件路径>`。
+const CONTROL_EXEMPT = new Set([
+  '@pagoda-dsh-workbench/module-cmdb:src/views/MenuField.tsx',
+  '@pagoda-dsh-workbench/module-cmdb:src/views/ChooseEnvsBody.tsx',
+]);
+
+/** 裸控件出现的位置 —— 逐行看不了（一个元素会跨行），所以在全文里按标签找，再回推行号。 */
+function bareControlsIn(text) {
+  const hits = [];
+  for (const one of BARE_CONTROLS) {
+    const pattern = new RegExp(
+      `(?:h\\(\\s*['"]${one.tag}['"]|jsx\\(\\s*['"]${one.tag}['"]|<${one.tag}(?=[\\s>/]))`,
+      'g',
+    );
+    for (const match of text.matchAll(pattern)) {
+      if (one.tag === 'input' && NATIVE_ONLY_INPUT.test(text.slice(match.index, match.index + 220))) continue;
+      hits.push({ ...one, line: text.slice(0, match.index).split('\n').length });
+    }
+  }
+  return hits;
+}
+
 const CLASS_TOKEN = /(^|[^-\w])\.?(wb-[a-zA-Z0-9-]+)/g;
 // 契约 = 外壳**所有**声明了 `wb-*` 的样式表，不只是那份全局 `board.css`：
 // ADR-0029 要求组件的样式跟组件走，所以 `wb-card` / `wb-rows` / `wb-note` 这些已经搬进
@@ -97,6 +138,7 @@ export async function run() {
   const problems = [];
   const borrowed = [];
   const anchors = [];
+  const controls = [];
   const modules = discoverModulePackages({ root: process.cwd() });
   const contracts = new Map(modules.map((pkg) => [pkg.dir, contractOf(pkg.dir)]));
   for (const pkg of modules) {
@@ -111,16 +153,18 @@ export async function run() {
       }
       const lines = text.split('\n');
       lines.forEach((line, index) => {
-        if (!RULE.test(line)) return;
-        const selector = line.slice(0, line.indexOf('{'));
-        if (!SHELL_SELECTOR.test(selector)) return;
-        problems.push(
-          `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 定义了外壳前缀的 CSS 规则 —— ${line.trim().slice(0, 100)}`,
-        );
+        for (const offender of shellRulesIn(line)) {
+          problems.push(
+            `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 定义了外壳类的 CSS 规则 —— ` +
+              `${offender}（这个复合选择器里没有模块自己的类：外壳的类谁渲染谁拥有，` +
+              '要改就跟外壳那位主人说，别在后面覆盖它）',
+          );
+        }
       });
 
       if (isTestSource(file)) continue;
       if (!/\.tsx?$/.test(file)) continue;
+      const exemptControls = CONTROL_EXEMPT.has(`${pkg.manifest.name}:${relative(pkg.dir, file)}`);
       lines.forEach((line, index) => {
         if (!BARE_ANCHOR.test(line)) return;
         anchors.push(
@@ -128,6 +172,15 @@ export async function run() {
             `外链一律用 kit 的 Link（新窗口、noopener、自带那个外链小箭头；样式只有这一份）：${line.trim().slice(0, 80)}`,
         );
       });
+      if (!exemptControls) {
+        for (const hit of bareControlsIn(text)) {
+          controls.push(
+            `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${hit.line} 手写了裸 <${hit.tag}>（${hit.what}）—— ` +
+              `用 ${hit.use}（手写的拿到的是浏览器默认样式：悬停、禁用、焦点环、色板都得自己抄，还不跟主题）：` +
+              `${(lines[hit.line - 1] ?? '').trim().slice(0, 80)}`,
+          );
+        }
+      }
       if (contract === null) continue;
       lines.forEach((line, index) => {
         for (const match of line.matchAll(CLASS_TOKEN)) {
@@ -169,7 +222,7 @@ export async function run() {
     }
   }
 
-  if (bindings.length + problems.length + borrowed.length + anchors.length > 0) {
+  if (bindings.length + problems.length + borrowed.length + anchors.length + controls.length > 0) {
     const notes = [];
     if (bindings.length > 0) {
       notes.push(
@@ -179,7 +232,9 @@ export async function run() {
     }
     if (problems.length > 0) {
       notes.push(
-        `${problems.length} 处是「模块不许定义外壳前缀的 CSS 规则」：（wb-* 是全局类名：两份同名规则按注入顺序互相覆盖，用户看到的是随机的那个）`,
+        `${problems.length} 处是「模块不许定义外壳类（wb-*）的 CSS 规则」：（wb-* 是外壳的命名空间：` +
+          '两份同名规则按注入顺序互相覆盖，用户看到的是随机的那个。判据看**复合选择器** —— ' +
+          '`:global(.wb-x)` 与 `.row :global(.wb-x)` 都算，只有同一个复合选择器里带了模块自己的类才放行）',
       );
     }
     if (borrowed.length > 0) {
@@ -195,8 +250,20 @@ export async function run() {
           '裸 <a> 拿到的是浏览器默认样式，看着和卡片其它地方不是一套）',
       );
     }
-    // 四类问题各自成串，按原来的输出顺序（绑定 → 规则 → 借用 → 裸 <a>）拼在一起。
-    return { status: 'fail', notes, problems: [...bindings, ...problems, ...borrowed, ...anchors] };
+    if (controls.length > 0) {
+      notes.push(
+        `${controls.length} 处是「手写了裸 <button>/<input>/<select>」：（kit 与 dsh 原语里都有对应形态 —— ` +
+          'Button / TextField / SelectField / ChoiceGroup；手写的那份拿到浏览器默认样式，' +
+          '悬停、禁用、焦点环、字号都得自己抄一遍，还不跟主题。只有多行输入 <textarea> 与 ' +
+          '`type="hidden"` / `type="file"` 例外：那两种形态两处都没有）',
+      );
+    }
+    // 各类问题各自成串，按原来的输出顺序（绑定 → 规则 → 借用 → 裸 <a> → 裸控件）拼在一起。
+    return {
+      status: 'fail',
+      notes,
+      problems: [...bindings, ...problems, ...borrowed, ...anchors, ...controls],
+    };
   }
 
   if (modules.length === 0) {

package/src/css-shell.mjs

@@ -0,0 +1,80 @@
+// 「模块碰了外壳的类」这套判断的**唯一一份**算法：源码判据（`checks/style.mjs`）与产物判据
+// （`checks/bundles.mjs`）都从这里取。两处各写一份必然漂，而漂了的那一份会让另一侧漏报。
+//
+// `wb-*` 是外壳的命名空间（全局类名，两份同名规则按注入顺序互相覆盖，用户看到的是随机的那个）。
+// 判据落在**复合选择器**上：一个复合选择器里只要有 `wb-*` 类、又没有任何模块自己的类
+// （CSS Modules 的哈希类，或模块自己起的名字），这条规则就是在替外壳那位主人定样子。两种写法都要认：
+//
+//     :global(.wb-approvalWarn) { … }      ← 主体就是外壳类
+//     .row :global(.wb-cmdbField) { … }    ← 后代里挂了外壳类
+//
+// 旧判据只看「`.wb-` 前面是不是分隔符」，于是 `:global(` 那个 `(` 把它挡住了 —— 这两种写法
+// 一个都看不见（实测：cmdb 的 `:global(.wb-approvalWarn)` 把外壳的告警色整页改掉了，判据全绿）。
+//
+// 反过来，「自己的节点 + 外壳的槽类」是**合规**的（外壳 `.scratch/dsh-ui-alignment/spec.md` §16 的
+// 条带钮就是这个形状：`Button variant="ghost"` + 调用点给的槽类），所以
+//
+//     .envRefresh:global(.wb-iconButton) { … }
+//
+// 不算 —— 同一个复合选择器里有模块自己的类，它改的是自己那颗钮。
+
+// 外壳的类名是 camelCase（`wb-cardBody` / `wb-iconButton`）—— 只写 `[a-z0-9-]` 会把它们全漏掉，
+// 而漏掉的方向是"判据以为自己在守、其实一条都没看"（旧判据只匹配前缀 `.wb-c`，所以没踩到）。
+const SHELL_CLASS = /^wb-[A-Za-z0-9-]+$/;
+const CLASS_TOKEN = /\.([A-Za-z_-][\w-]*)/g;
+// 只看**像选择器**的那段文本：JSX / JS 那几行（`h("div", {`、`const x = {`、`<div className=`）带引号、
+// 等号或尖括号，一律不认（源码文件与产物都要一份能同时读 CSS 与 JS 的判断）。
+const SELECTOR_TEXT = /^[\s,>+~.:#*()&[\]\w-]*$/;
+
+function compoundsOf(selector) {
+  return selector
+    .split(',')
+    .flatMap((part) => part.trim().split(/[\s>+~]+/))
+    .filter((compound) => compound !== '');
+}
+
+function classesIn(compound) {
+  return Array.from(compound.matchAll(CLASS_TOKEN), (match) => match[1]);
+}
+
+/** 选择器里第一个「只由外壳类构成」的复合选择器；一个都没有就是 undefined。 */
+export function shellOnlyCompound(selector) {
+  if (!SELECTOR_TEXT.test(selector)) return undefined;
+  return compoundsOf(selector).find((compound) => {
+    const classes = classesIn(compound);
+    return classes.length > 0 && classes.every((name) => SHELL_CLASS.test(name));
+  });
+}
+
+/** 一份样式表里被定义/覆盖的外壳规则（选择器，含外壳命名空间的 keyframes）。 */
+export function shellRulesIn(cssText) {
+  const found = [];
+  for (const line of cssText.split('\n')) {
+    const brace = line.indexOf('{');
+    if (brace >= 0 && shellOnlyCompound(line.slice(0, brace)) !== undefined) {
+      found.push(line.slice(0, brace).trim());
+    }
+    const keyframes = /@keyframes\s+(wb-[a-z0-9-]+)/.exec(line);
+    if (keyframes !== null) found.push(`@keyframes ${keyframes[1]}`);
+  }
+  return found;
+}
+
+/** 模块**产物**里被内联进来的外壳规则（第二份实例的物证）。 */
+export function inlinedShellRules(artifactText) {
+  // 产物里的 CSS 是 JS 字符串：换行是字面两字符 `\n`，先还原成真换行才谈得上按规则切。
+  const text = artifactText.replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+  const found = [];
+  // 规则的起点不一定在行首 —— CSS 就住在 `var css = "…"` 里（`".wb-cardBody {`），所以引号、
+  // 分号、花括号都算边界。捕获的字符集与选择器同宽（不含引号/等号/尖括号）：否则一条 `var x = "…"`
+  // 会从它自己的换行处起 match、把后面那个真规则的起点一起吞掉（实测：真规则在同一行后面时漏报）。
+  for (const match of text.matchAll(/(?:^|[\n;{}"'])[ \t]*([\s,>+~.:#*()&[\]\w-]*?)[ \t]*\{/gm)) {
+    const selector = match[1];
+    if (selector.trimStart().startsWith('@')) continue;
+    if (shellOnlyCompound(selector) !== undefined) found.push(selector.trim());
+  }
+  for (const match of text.matchAll(/@keyframes\s+(wb-[a-z0-9-]+)/g)) {
+    found.push(`@keyframes ${match[1]}`);
+  }
+  return [...new Set(found)];
+}

package/src/init.mjs

@@ -14,7 +14,7 @@ export async function init({ root, args = [] }) {
   if (unit === undefined || !UNIT_ID.test(unit)) {
     console.error('用法：dsh-wb-module init <unit> [--dir <目录>] [--template minimal|diy] [--description <文字>]');
     console.error('  unit 是小写短横线标识（它同时是单元 id、包名后缀、卡片 class 前缀）');
-    console.error('  --template diy：带一个真数据源 + 三态 + ?wbMock=1 夹具的样板（默认 minimal 是空壳）');
+    console.error('  --template diy：带一个真数据源 + 卡片的样板（默认 minimal 是空壳）');
     process.exit(2);
   }
   const picked = args[args.indexOf('--template') + 1];

package/template/scripts/smoke.mjs.tpl

@@ -5,7 +5,7 @@
 // 于是"模块注册的卡片到底进没进外壳"变成一条机器判据，而不再是人的眼睛。
 //
 // ★ 这份脚本只验**形状**：它认不出成员名、也不认识你的数据源，所以换数据源、换卡片内容都不用改它。
-//   你自己的那条读该不该跑通，属于 `?wbMock=1` 三档夹具与你自己 vitest 的事。
+//   你自己的那条读该不该跑通，属于你自己 vitest 与 `pnpm selfcheck` 的事。
 //
 // 负例在最后一段：服务不在的时候必须**报出来**，不许静默通过 —— 静默的模块是最难查的那种坏。
 

package/template-diy/README.md.tpl

@@ -17,7 +17,7 @@ dsh-wb-module check --only cards   # 十条可以单跑
 ```bash
 pnpm build        # 构建产物
 pnpm typecheck    # tsc --noEmit
-pnpm test         # vitest：路由真读数 + 卡片五态 + 三种夹具
+pnpm test         # vitest：路由真读数 + 卡片五态
 pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍 + 调一次 <unit>/overview 看它真读盘
 ```
 
@@ -91,9 +91,9 @@ pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍 + 调
 | `package.json` | 自述清单：`dsh.workbench.unit` = `__UNIT__`、两个面（`src/host.ts` / `src/client.tsx`）、四个脚本、peer 下限 |
 | `cordis.patch.yml` | 插进 dsh 组合的补丁 |
 | `src/host.ts` | 宿主面：`readOverview()`（真读目录）+ 一条只读路由 `<unit>/overview` |
-| `src/client.tsx` | 卡片：`Card` 壳 + 五态（待机 / 加载 / 就绪 / 出错，其中"就绪但空"单列一态）+ `?wbMock=1` 夹具 |
+| `src/client.tsx` | 卡片：`Card` 壳 + 五态（待机 / 加载 / 就绪 / 出错，其中"就绪但空"单列一态） |
 | `src/messages.ts` | 卡片那几句文案（zh / en） |
-| `src/plugin.test.ts` | 面注册 + 路由真读 + 五态 + 三种夹具的断言 |
+| `src/plugin.test.ts` | 面注册 + 路由真读 + 五态的断言 |
 | `scripts/smoke.mjs` | 接线自检：卡片进没进外壳、路由真读没真读 |
 | `tsconfig.json` / `vitest.config.ts` / `types/globals.d.ts` | 经典 JSX 运行时（`jsxFactory: h`）、vitest 的别名、浏览器半侧的运行时垫片 |
 | `README.md` | 就是本文 |
@@ -222,12 +222,12 @@ env: {
 }
 ```
 
-外壳的隔离运行时按它装、按它探（`workbench_modules list` 里逐条看得到）。**没装好时用户看到的那句话
+外壳的隔离运行时按它装、按它探（`workbench_modules_list` 里逐条看得到）。**没装好时用户看到的那句话
 由你写**：`libInstallCommand({ need })` 会连源和缓存目录一起拼好，原样给他，别自己拼 npm 命令。
 
 ## 卡片画哪五态
 
-`src/client.tsx` 的 `overviewStateOf({ fixture, phase, value, error })` 是一条纯函数，
+`src/client.tsx` 的 `overviewStateOf({ phase, value, error })` 是一条纯函数，
 每个分支各对应一屏（`src/plugin.test.ts` 一屏一屏断言）：
 
 | 态 | 什么时候 | 画什么 |
@@ -236,29 +236,12 @@ env: {
 | 加载 | 还没有值（首读），或 `phase === 'error'` 之外什么都没来 | `CenteredState`：正在读目录 |
 | 就绪 | 有值，且文件数 + 目录数 > 0 | `StateBlock`：路径 + 「N 个文件 · M 个目录 · 总字节」+ 最大的几个文件列表 |
 | 就绪但空 | 有值，但文件数 = 目录数 = 0 | `EmptyState`：这个目录是空的 |
-| 出错 | `phase === 'error'`（或夹具给的是错误） | `CenteredState`：读不到这个目录 + 宿主的原话 |
-
-待机那一屏要排在夹具**之后**：`?wbMock=1` 且没开项目时，夹具仍然要演得出来（否则
-"读不到"这种状态在没有项目时就永远看不到，而那正是干净 profile 下的评审场景）。
+| 出错 | `phase === 'error'` | `CenteredState`：读不到这个目录 + 宿主的原话 |
 
 刷新时 `useApiResource` 会把 `phase` 打成 `loading` **同时保留上一次的 `value`** ——
 这时刻意继续画旧数据（右上角的转圈由 `Card` 的 `refreshing` 表示），不退回骨架：
 一次刷新不该让整张卡闪一下。
 
-## `?wbMock=1` 夹具
-
-打开 `?wbMock=1`（搜索串里含 `wbMock=1`）时卡片顶上多一条 `MockStrip`，
-`kit.hooks.useFixturePick` 提供三个夹具，**只切状态、不发请求**：
-
-| id | 标签 | 演的是 |
-|---|---|---|
-| `ready` | 有数据 | 128 个文件 / 12 个目录 / 3 MB，带三个最大的文件 |
-| `empty` | 空目录 | 就绪但那一路"空"态 |
-| `error` | 读不到 | `EACCES: permission denied, scandir /mock/secret` |
-
-夹具优先于真请求：只要 mock 开着，画的就是夹具那一屏。
-改夹具时顺手改一眼 `src/plugin.test.ts` 的「夹具」那一组断言 —— 那组就是守它的。
-
 ## 装进本地工作台
 
 ```bash

package/template-diy/src/client.tsx.tpl

@@ -7,8 +7,8 @@ const OVERVIEW_ROUTE = `${UNIT_ID}/overview`;
 const LIST_LIMIT = 5;
 const KB = 1024;
 
-const { Card, MockStrip, CenteredState, EmptyState, StateBlock, IconPanelScreen } = kit.components;
-const { useApiResource, useFixturePick } = kit.hooks;
+const { Card, CenteredState, EmptyState, Row, Rows, StateBlock, IconPanelScreen } = kit.components;
+const { useApiResource } = kit.hooks;
 
 type Rendered = ReturnType<typeof h>;
 type Translate = (key: string, params?: Record<string, unknown>) => string;
@@ -60,13 +60,6 @@ interface Failure {
   readonly message: string;
 }
 
-export interface Fixture {
-  readonly id: string;
-  readonly label: string;
-  readonly payload?: OverviewPayload;
-  readonly error?: Failure;
-}
-
 export type OverviewState =
   | { readonly kind: 'idle' }
   | { readonly kind: 'loading' }
@@ -75,36 +68,11 @@ export type OverviewState =
   | { readonly kind: 'error'; readonly detail: string };
 
 export interface OverviewInput {
-  readonly fixture: Fixture | undefined;
   readonly phase: 'idle' | 'loading' | 'ready' | 'error';
   readonly value: OverviewReady | undefined;
   readonly error: Failure | undefined;
 }
 
-const fixtureFiles: readonly OverviewFile[] = [
-  { name: 'client.js', bytes: 182400, mtime: '2026-01-05T09:12:44.000Z' },
-  { name: 'host.js', bytes: 96256, mtime: '2026-01-05T09:12:44.000Z' },
-  { name: 'pnpm-lock.yaml', bytes: 41984, mtime: '2026-01-04T18:02:10.000Z' },
-];
-
-export const overviewFixtures: readonly Fixture[] = [
-  {
-    id: 'ready',
-    label: '有数据',
-    payload: { path: '/mock/workbench', files: 128, dirs: 12, bytes: 3145728, largest: fixtureFiles },
-  },
-  {
-    id: 'empty',
-    label: '空目录',
-    payload: { path: '/mock/empty', files: 0, dirs: 0, bytes: 0, largest: [] },
-  },
-  {
-    id: 'error',
-    label: '读不到',
-    error: { code: 'overview-unreadable', message: 'EACCES: permission denied, scandir /mock/secret' },
-  },
-];
-
 export function formatBytes(bytes: number): string {
   if (bytes < KB) return `${String(bytes)} B`;
   if (bytes < KB * KB) return `${(bytes / KB).toFixed(1)} KB`;
@@ -118,11 +86,6 @@ function payloadState(payload: OverviewPayload): OverviewState {
 }
 
 export function overviewStateOf(input: OverviewInput): OverviewState {
-  const fixture = input.fixture;
-  if (fixture !== undefined) {
-    if (fixture.error !== undefined) return { kind: 'error', detail: fixture.error.message };
-    if (fixture.payload !== undefined) return payloadState(fixture.payload);
-  }
   if (input.phase === 'idle') return { kind: 'idle' };
   if (input.phase === 'error') {
     const error = input.error;
@@ -177,10 +140,14 @@ function bodyOf(state: OverviewState, t: Translate): Rendered {
       resolving: t(`${UNIT_ID}.largest`),
     },
     h(
-      'ul',
+      Rows,
       null,
       ...payload.largest.map((file) =>
-        h('li', { key: file.name }, `${file.name} · ${formatBytes(file.bytes)} · ${file.mtime}`),
+        h(Row, {
+          key: file.name,
+          label: file.name,
+          value: `${formatBytes(file.bytes)} · ${file.mtime}`,
+        }),
       ),
     ),
   );
@@ -198,9 +165,7 @@ const face: UnitClientFace = {
       props.refreshToken,
       { enabled: path !== '' },
     );
-    const mock = useFixturePick<Fixture>({ fixtures: overviewFixtures, initial: 'ready' });
     const state = overviewStateOf({
-      fixture: mock.enabled ? mock.current : undefined,
       phase: resource.phase,
       value: resource.value,
       error: resource.error,
@@ -213,14 +178,6 @@ const face: UnitClientFace = {
         refreshing: resource.phase === 'loading',
         onRefresh: props.onRefresh,
       },
-      mock.enabled
-        ? h(MockStrip, {
-            mocks: overviewFixtures,
-            index: mock.index,
-            onPick: (next: number) => mock.pick(overviewFixtures[next]?.id ?? null),
-            note: props.t(`${UNIT_ID}.mockNote`),
-          })
-        : null,
       bodyOf(state, props.t),
     );
   },

package/template-diy/src/messages.ts.tpl

@@ -10,7 +10,6 @@ export const messages = {
     '__UNIT__.largest': '最大的几个文件',
     '__UNIT__.fileUnit': ' 个文件',
     '__UNIT__.dirUnit': ' 个目录',
-    '__UNIT__.mockNote': '夹具：只切状态，不发请求',
   },
   en: {
     '__UNIT__.cardTitle': 'Directory overview',
@@ -23,6 +22,5 @@ export const messages = {
     '__UNIT__.largest': 'Largest files',
     '__UNIT__.fileUnit': ' files',
     '__UNIT__.dirUnit': ' dirs',
-    '__UNIT__.mockNote': 'Fixtures: switches state only, no request',
   },
 };

package/template-diy/src/plugin.test.ts.tpl

@@ -4,8 +4,6 @@ import { join } from 'node:path';
 import { afterAll, describe, expect, it, vi } from 'vitest';
 
 const shell = vi.hoisted(() => ({
-  enabled: false,
-  fixture: undefined as { readonly id: string } | undefined,
   resource: { phase: 'loading' } as {
     readonly phase: string;
     readonly value?: unknown;
@@ -21,18 +19,9 @@ vi.mock('@dsh-workbench/core/client', () => ({
         shell.readEnabled = options?.enabled;
         return shell.resource;
       },
-      useFixturePick: () => ({
-        enabled: shell.enabled,
-        active: shell.fixture?.id ?? null,
-        current: shell.fixture,
-        pick: () => {},
-        nonce: 0,
-        index: 0,
-      }),
     },
     components: {
       Card: () => null,
-      MockStrip: () => null,
       CenteredState: () => null,
       EmptyState: () => null,
       StateBlock: () => null,
@@ -42,13 +31,7 @@ vi.mock('@dsh-workbench/core/client', () => ({
 }));
 
 import { apply, inject, name, OVERVIEW_ROUTE, readOverview } from './host';
-import {
-  apply as applyClient,
-  formatBytes,
-  inject as injectClient,
-  overviewFixtures,
-  overviewStateOf,
-} from './client';
+import { apply as applyClient, formatBytes, inject as injectClient, overviewStateOf } from './client';
 
 interface HostFace {
   readonly unit: string;
@@ -221,8 +204,6 @@ describe('宿主侧的只读路由', () => {
 describe('卡片：待机 / 加载 / 就绪 / 就绪但空 / 出错', () => {
   it('没有选中工作区时不发请求，画待机那一屏', () => {
     const face = clientFace();
-    shell.enabled = false;
-    shell.fixture = undefined;
     shell.resource = { phase: 'idle' };
     const withoutProject = { ...cardProps, world: { current: { workspace: null } } };
 
@@ -234,19 +215,8 @@ describe('卡片：待机 / 加载 / 就绪 / 就绪但空 / 出错', () => {
     expect(shell.readEnabled).toBe(true);
   });
 
-  it('没有工作区时夹具照样能演（夹具优先于待机）', () => {
-    const face = clientFace();
-    shell.enabled = true;
-    shell.fixture = overviewFixtures[0];
-    shell.resource = { phase: 'idle' };
-    const withoutProject = { ...cardProps, world: { current: { workspace: null } } };
-    expect(textOf(face.card(withoutProject)).join(' ')).toContain('/mock/workbench');
-  });
-
   it('四态各画得出来', () => {
     const face = clientFace();
-    shell.enabled = false;
-    shell.fixture = undefined;
 
     shell.resource = { phase: 'loading' };
     expect(textOf(face.card(cardProps)).join(' ')).toContain('__UNIT__.loading');
@@ -281,8 +251,6 @@ describe('卡片：待机 / 加载 / 就绪 / 就绪但空 / 出错', () => {
 
   it('刷新中旧数据还在（不退回加载态）', () => {
     const face = clientFace();
-    shell.enabled = false;
-    shell.fixture = undefined;
     shell.resource = {
       phase: 'loading',
       value: { ok: true, path: '/real/workbench', files: 1, dirs: 0, bytes: 10, largest: [] },
@@ -292,65 +260,33 @@ describe('卡片：待机 / 加载 / 就绪 / 就绪但空 / 出错', () => {
     expect(text).not.toContain('__UNIT__.loading');
   });
 
-  it('只有 mock 模式才挂出夹具条', () => {
-    const face = clientFace();
-    shell.fixture = undefined;
-    shell.resource = { phase: 'loading' };
-
-    shell.enabled = false;
-    expect(textOf(face.card(cardProps)).join(' ')).not.toContain('__UNIT__.mockNote');
-
-    shell.enabled = true;
-    const text = textOf(face.card(cardProps)).join(' ');
-    expect(text).toContain('__UNIT__.mockNote');
-    expect(text).toContain('空目录');
-  });
 });
 
-describe('夹具：?wbMock=1 下三种状态都演得出来', () => {
-  it('三个夹具各自解出一个状态（有数据 / 空 / 读不到）', () => {
-    expect(overviewFixtures.map((fixture) => fixture.id)).toEqual(['ready', 'empty', 'error']);
-    const kinds = overviewFixtures.map(
-      (fixture) =>
-        overviewStateOf({
-          fixture,
-          phase: 'error',
-          value: undefined,
-          error: { code: 'network', message: '夹具优先于真请求' },
-        }).kind,
-    );
-    expect(kinds).toEqual(['ready', 'empty', 'error']);
-  });
-
-  it('夹具优先于真请求：三种都画得出来', () => {
-    const face = clientFace();
-    shell.enabled = true;
-    shell.resource = { phase: 'loading' };
-
-    shell.fixture = overviewFixtures[0];
-    const ready = textOf(face.card(cardProps)).join(' ');
-    expect(ready).toContain('/mock/workbench');
-    expect(ready).toContain('client.js');
-
-    shell.fixture = overviewFixtures[1];
-    expect(textOf(face.card(cardProps)).join(' ')).toContain('__UNIT__.empty');
-
-    shell.fixture = overviewFixtures[2];
-    expect(textOf(face.card(cardProps)).join(' ')).toContain('EACCES');
-  });
-
-  it('夹具数据自己的形状也有人守', () => {
-    const ready = overviewFixtures[0]?.payload;
-    expect(ready?.files).toBeGreaterThan(0);
-    expect(ready?.dirs).toBeGreaterThan(0);
-    expect(ready?.bytes).toBeGreaterThan(0);
-    expect(ready?.largest).toHaveLength(3);
-    expect(Number.isNaN(Date.parse(ready?.largest[0]?.mtime ?? ''))).toBe(false);
-    expect(overviewFixtures[1]?.payload?.files).toBe(0);
-    expect(overviewFixtures[1]?.payload?.largest).toHaveLength(0);
-    expect(overviewFixtures[2]?.error?.message).toContain('EACCES');
+describe('状态映射', () => {
+  it('phase 与读数一起解出那一屏（待机 / 加载 / 就绪 / 就绪但空 / 出错）', () => {
+    const at = (input: Parameters<typeof overviewStateOf>[0]): string => overviewStateOf(input).kind;
+
+    expect(at({ phase: 'idle', value: undefined, error: undefined })).toBe('idle');
+    expect(at({ phase: 'loading', value: undefined, error: undefined })).toBe('loading');
+    expect(
+      at({
+        phase: 'ready',
+        value: { ok: true, path: '/p', files: 2, dirs: 1, bytes: 10, largest: [] },
+        error: undefined,
+      }),
+    ).toBe('ready');
+    expect(
+      at({
+        phase: 'ready',
+        value: { ok: true, path: '/p', files: 0, dirs: 0, bytes: 0, largest: [] },
+        error: undefined,
+      }),
+    ).toBe('empty');
+    expect(at({ phase: 'error', value: undefined, error: { code: 'internal', message: 'boom' } })).toBe('error');
   });
+});
 
+describe('格式化', () => {
   it('字节格式化不炸也不乱', () => {
     expect(formatBytes(0)).toBe('0 B');
     expect(formatBytes(2048)).toBe('2.0 KB');