@dsh-workbench/module-tools 0.2.12 → 0.2.14

package/src/checks/cards.mjs

@@ -1,28 +1,24 @@
-// 模块卡片能不能**画出来**（S1 视觉验收里唯一能机器化的那一半）。
-//
-// 「卡片出现」这句话里有两件事：
-//   ① 结构画得出来 —— 卡片的代码跑得通、返回一棵非空元素树。**这条能机器验**；
-//   ② 画成什么样（间距、颜色、两栏还是三栏）—— 只有人眼能判，这里不碰。
-//
-// 为什么用「空数据」当输入：外壳渲染卡片时，数据往往还没回来（第一次读、卡在审批、
-// 平台没登录）。所以**卡片在拿到空数据时不许抛** —— 这正是"卡片一直不出来 / 点一下白屏"
-// 那类事故的机器形态。给了数据才跑得通的卡片，等于把崩溃留到用户面前。
-//
-// 手法与 packages/workbench/scripts/selfcheck.mjs 里那套一致：产物是
-// `window.__ModuleLoader__.load({id, factory})`，用假的 loader / require 把它拉起来。
-// 覆盖范围跟着 `dsh.workbench` 自述清单走 —— 新模块不用改这里。
-//
-// 形状（所有判据统一）：导出 `title` 与 `run()`，`run()` 返回三态结果；
-// 打印与退出码归 `../check.mjs` 那一层。
-
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
 import { discoverModulePackages } from '../discover.mjs';
+import { shellClientPathOf, shellKitOf } from './shell-artifact.mjs';
 
 export const title = '卡片渲染';
 
-// 任何属性都拿得到、任何调用都返回自己的替身 —— 这样「外壳还没给数据」的各种形状
-// 都不会让卡片因为我们**没桩到某个字段**而假红。真红只留给卡片自己的代码。
+const LANGUAGES = ['zh', 'en'];
+
+const FORBIDDEN = [
+  { token: 'undefined', pattern: /\bundefined\b/ },
+  { token: 'NaN', pattern: /\bNaN\b/ },
+  { token: '[object Object]', pattern: /\[object Object\]/ },
+  { token: 'null', pattern: /\bnull\b/ },
+];
+
+const WORKSPACE = { path: '/tmp/repo', workspaceId: 'wb-card-probe' };
+
 function anyStub(path = 'stub') {
   const target = function () {
     return anyStub(`${path}()`);
@@ -42,12 +38,105 @@ function anyStub(path = 'stub') {
   });
 }
 
+function containerStub(path, size) {
+  const elementAt = (index) => containerStub(`${path}[${index}]`, size);
+  const asArray = () => Array.from({ length: size }, (_unused, index) => elementAt(index));
+  const scalar = size > 0 ? 1 : 0;
+  const methods = {
+    map: (fn) => asArray().map(fn),
+    filter: (fn) => asArray().filter(fn),
+    forEach: (fn) => asArray().forEach(fn),
+    find: (fn) => asArray().find(fn),
+    findIndex: (fn) => asArray().findIndex(fn),
+    some: (fn) => asArray().some(fn),
+    every: (fn) => asArray().every(fn),
+    reduce: (fn, initial) => asArray().reduce(fn, initial),
+    flatMap: (fn) => asArray().flatMap(fn),
+    slice: (from, to) => asArray().slice(from, to),
+    at: (index) => asArray().at(index),
+    indexOf: (value) => asArray().indexOf(value),
+    includes: (value) => asArray().includes(value),
+    join: (separator) => asArray().join(separator),
+    concat: (other) => asArray().concat(other),
+    reverse: () => asArray().reverse(),
+    sort: () => asArray(),
+    keys: () => asArray().keys(),
+    values: () => asArray().values(),
+    entries: () => asArray().entries(),
+    toArray: () => asArray(),
+  };
+  return new Proxy(function () {}, {
+    get(_target, key) {
+      if (key === 'ok') return true;
+      if (key === Symbol.toPrimitive) return () => scalar;
+      if (key === Symbol.iterator) return () => asArray()[Symbol.iterator]();
+      if (key === 'then') return undefined;
+      if (key === 'length') return size;
+      if (key === 'toString' || key === 'valueOf') return () => scalar;
+      if (key === 'constructor') return Object;
+      if (key in methods) return methods[key];
+      if (typeof key === 'symbol') return undefined;
+      return containerStub(`${path}.${String(key)}`, size);
+    },
+    apply() {
+      return containerStub(`${path}()`, size);
+    },
+  });
+}
+
+const SNAPSHOTS = [
+  { name: 'idle', resource: { phase: 'idle' }, workspace: null },
+  { name: 'loading', resource: { phase: 'loading' }, workspace: WORKSPACE },
+  { name: 'ready', resource: { phase: 'ready', value: containerStub('api', 2) }, workspace: WORKSPACE },
+  {
+    name: 'empty（有值但容器空）',
+    resource: { phase: 'ready', value: containerStub('api', 0) },
+    workspace: WORKSPACE,
+  },
+  {
+    name: 'unreadable',
+    resource: { phase: 'error', error: { code: 'network', message: '宿主没有响应' } },
+    workspace: WORKSPACE,
+  },
+  // P2 第一条：刷新形态（ADR-0022「刷新保留旧值」）。载荷与 `loading` 只差一格 —— `value` 在，
+  // 而且是旧那份。`use-api-resource.ts:100-104` 在同一个 identity 重读时给的就是这一相，卡片
+  // 若把"loading 就没有值"写死，脏就出在这一帧。注意它按 spec 只带 `value`、不带 `at`
+  // （真实那一相还会带 `prev.at`）—— 这是与真壳的一处已知出入，记在 spec 的 §7.3。
+  {
+    name: 'loading（刷新：保留旧值）',
+    resource: { phase: 'loading', value: containerStub('api', 2) },
+    workspace: WORKSPACE,
+  },
+  // P2 第二条：能力闸。`useCapabilityGate` 给一个**明确的** `missing-plugin`（不是 `null`）：
+  // `use-unit-board.ts:47` 对 `capability === null` 直接不算 `blockerOfCapability`，喂 null 就退化成
+  // P1 的 idle 那一屏、一格新代码都走不到。`gated` 由能力状态按 `gateOf`（`unit-board.ts:13-17`）
+  // 算出来（missing-plugin ⇒ false），`resource` 照 `ready` 一份 —— 于是它跟 `ready` 只差闸这一格，
+  // 阻断屏与正文同时在场时谁优先是模块的事。
+  {
+    name: 'unreadable（能力闸：缺插件）',
+    resource: { phase: 'ready', value: containerStub('api', 2) },
+    workspace: WORKSPACE,
+    capability: (unit) => ({
+      unit,
+      status: 'missing-plugin',
+      required: ['demo-plugin'],
+      missing: ['demo-plugin'],
+      detail: '逐态探针：缺 demo-plugin',
+    }),
+  },
+];
+
 function fakeReact() {
   const element = (type, props, ...children) => ({ type, props: props ?? {}, children });
-  return {
+  const passthrough = (props, ...children) => element('stub:passthrough', props, ...children);
+  const base = {
     createElement: element,
     createElementNS: (_namespace, type, props, ...children) => element(type, props, ...children),
     Fragment: 'Fragment',
+    Component: class {},
+    PureComponent: class {},
+    createContext: (value) => ({ Provider: passthrough, Consumer: passthrough, _currentValue: value }),
+    useContext: () => anyStub('context'),
     useState: (initial) => [typeof initial === 'function' ? initial() : initial, () => {}],
     useReducer: (_reducer, initial) => [initial, () => {}],
     useMemo: (factory) => factory(),
@@ -55,20 +144,52 @@ function fakeReact() {
     useRef: (initial) => ({ current: initial ?? null }),
     useEffect: () => {},
     useLayoutEffect: () => {},
+    useInsertionEffect: () => {},
     useSyncExternalStore: (_subscribe, snapshot) => snapshot(),
     useId: () => 'wb-id',
+    useTransition: () => [false, (fn) => fn()],
+    useDeferredValue: (value) => value,
     isValidElement: (value) => typeof value === 'object' && value !== null && 'type' in value,
-    Children: { toArray: (value) => (Array.isArray(value) ? value : [value]) },
+    cloneElement: (node, props, ...children) =>
+      element(node.type, { ...(node.props ?? {}), ...(props ?? {}) }, ...children),
+    memo: (fn) => fn,
+    forwardRef: (fn) => fn,
+    Children: {
+      toArray: (value) =>
+        Array.isArray(value) ? value : value === undefined || value === null ? [] : [value],
+      map: (value, fn) =>
+        (Array.isArray(value) ? value : value === undefined || value === null ? [] : [value]).map(fn),
+      count: (value) =>
+        Array.isArray(value) ? value.length : value === undefined || value === null ? 0 : 1,
+    },
+  };
+  return new Proxy(base, { get: (target, key) => (key in target ? target[key] : () => null) });
+}
+
+function fakeJsxRuntime() {
+  const react = fakeReact();
+  return {
+    Fragment: react.Fragment,
+    jsx: (type, props) => react.createElement(type, props, ...(props?.children ?? [])),
+    jsxs: (type, props) => react.createElement(type, props, ...(props?.children ?? [])),
+    jsxDEV: (type, props) => react.createElement(type, props, ...(props?.children ?? [])),
   };
 }
 
+function fakeDshPackage() {
+  const stub = (props) => ({
+    type: 'stub:dsh',
+    props: props ?? {},
+    children:
+      props?.children === undefined ? [] : Array.isArray(props.children) ? props.children : [props.children],
+  });
+  return new Proxy({}, { get: () => stub });
+}
+
 function fakeKit() {
   const callable = () => anyStub('result');
   return {
     hooks: new Proxy({}, { get: () => callable }),
-    // 组件替身**带上自己的名字**（`stub:Card`）：卡片壳现在是 `kit.components.Card` 这个组件，
-    // 产物里不会再出现 `wb-card` 这个类名 —— 判据要能认出"用了外壳给的卡壳"。
-    // children 要**往下传**：吞掉的话，卡片体内用 kit 组件写的内容就永远渲染不到（节点数会假少）。
     components: new Proxy(
       {},
       {
@@ -87,23 +208,9 @@ function fakeKit() {
   };
 }
 
-/**
- * dsh 的客户端包（平台种子词）在**卡片渲染**这里的替身。
- *
- * 模块的产物里 `require("@deepseek-ai/dsh-client-ui-primitives")` 是**规范**（ADR-0028：
- * 标成 external 才是"用外壳那一份"）。判据在 node 里跑产物，就得像外壳的模块表那样把这些
- * 种子词交出去 —— 不然合规的模块反而卡在"没桩的外部"（实际上就是这么发现的）。
- * 组件与 hooks 都长成函数：卡片判据只问"画不画得出非空元素树"。
- */
-function fakeDshPackage() {
-  const stub = (props) => ({ type: 'stub', props: props ?? {}, children: [] });
-  return new Proxy({}, { get: (_target, key) => (key === 'default' ? stub : stub) });
-}
-
-function loadFace(clientFile) {
+function loadFace(clientFile, makeKit) {
   let captured;
   const fakeWindow = {
-    // 浏览器里 `window.location` 永远在；缺了它，读它的客户端代码（含 `?wbMock=1` 那个开关）会先抛。
     location: { search: '', href: 'http://127.0.0.1:3081/' },
     __ModuleLoader__: {
       load: (entry) => {
@@ -121,7 +228,8 @@ function loadFace(clientFile) {
   expose.exports = module.exports;
   const fakeRequire = (id) => {
     if (id === 'react') return fakeReact();
-    if (id === '@dsh-workbench/core/client') return { kit: fakeKit() };
+    if (id === 'react/jsx-runtime' || id === 'react/jsx-dev-runtime') return fakeJsxRuntime();
+    if (id === '@dsh-workbench/core/client') return { kit: makeKit() };
     if (id.startsWith('@deepseek-ai/')) return fakeDshPackage();
     throw new Error(`产物 require 了没桩的外部：${id}`);
   };
@@ -129,23 +237,29 @@ function loadFace(clientFile) {
   return { id: captured.id, exports: produced ?? module.exports };
 }
 
-// 递归**调用**函数组件 —— 不调用的话，树里只有最外层那个 `type`，
-// 卡片体内的代码一行都没跑（第一次写漏了这步，4 张卡片都只数出 3 个节点）。
-//
-// 顺手把**用到的类名**收集起来：卡片得自己套外壳的卡片契约类（见文件尾那条判据）。
 function render(node, depth, budget) {
   if (node === null || node === undefined || typeof node === 'boolean') return 0;
-  if (typeof node === 'string' || typeof node === 'number') return 1;
+  if (typeof node === 'string' || typeof node === 'number') {
+    budget.texts.push(String(node));
+    return 1;
+  }
   if (Array.isArray(node)) {
     let count = 0;
     for (const one of node) count += render(one, depth, budget);
     return count;
   }
-  if (typeof node !== 'object') return 1;
+  if (typeof node !== 'object') {
+    budget.texts.push(String(node));
+    return 1;
+  }
   if (budget.left <= 0) return 0;
   budget.left -= 1;
   budget.maxDepth = Math.max(budget.maxDepth, depth);
-
+  for (const [key, value] of Object.entries(node.props ?? {})) {
+    if (key === 'key' || key === 'ref') continue;
+    if (typeof value === 'string') budget.texts.push(value);
+    else if (typeof value === 'number' && Number.isNaN(value)) budget.texts.push('NaN');
+  }
   const classes = node.props?.className;
   if (typeof classes === 'string') {
     for (const one of classes.split(/\s+/)) if (one !== '') budget.classNames.add(one);
@@ -153,7 +267,6 @@ function render(node, depth, budget) {
   if (typeof node.type === 'string' && node.type.startsWith('stub:')) {
     budget.stubs.add(node.type.slice('stub:'.length));
   }
-
   const children = [...(node.children ?? [])];
   if (typeof node.type === 'function') {
     if (depth > 40) throw new Error('组件递归超过 40 层（自引用？）');
@@ -165,10 +278,75 @@ function render(node, depth, budget) {
   return count;
 }
 
+async function shellDictionariesOf() {
+  const require = createRequire(import.meta.url);
+  const entry = require.resolve('@dsh-workbench/shared');
+  const module = await import(pathToFileURL(join(dirname(entry), 'i18n/index.js')).href);
+  return module.dictionaries;
+}
+
+function ownOf(dictionaries, language) {
+  const one = dictionaries?.[language];
+  return typeof one === 'object' && one !== null ? one : {};
+}
+
+function translatorOf(language, messages, shellDictionaries, missing, snapshot) {
+  const own = ownOf(messages, language);
+  const shell = ownOf(shellDictionaries, language);
+  return (key, params) => {
+    const template = typeof own[key] === 'string' ? own[key] : shell[key];
+    if (typeof template !== 'string') {
+      missing.push({ language, key, snapshot });
+      return `\u0000missing:${key}\u0000`;
+    }
+    if (params === undefined || params === null) return template;
+    return template.replace(/\{(\w+)\}/g, (whole, name) =>
+      name in params ? String(params[name]) : whole,
+    );
+  };
+}
+
+function forbiddenHitsOf(texts) {
+  const hits = [];
+  const seen = new Set();
+  for (const text of texts) {
+    for (const { token, pattern } of FORBIDDEN) {
+      if (!pattern.test(text)) continue;
+      const key = `${token}\u0000${text}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      hits.push({ token, text });
+    }
+  }
+  return hits;
+}
+
+function shellClientsOf(modulePackages) {
+  const found = new Set();
+  for (const pkg of modulePackages) {
+    const client = shellClientPathOf(pkg.dir);
+    if (client !== undefined && existsSync(client)) found.add(client);
+  }
+  return [...found];
+}
+
 export async function run() {
   const modulePackages = discoverModulePackages({ root: process.cwd() });
   const problems = [];
   const rows = [];
+  const footnotes = [];
+  let degraded = 0;
+
+  let shellDictionaries;
+  try {
+    shellDictionaries = await shellDictionariesOf();
+  } catch (error) {
+    shellDictionaries = undefined;
+    footnotes.push(
+      `（取不出 @dsh-workbench/shared 的字典：${error instanceof Error ? error.message : String(error)}）` +
+        ' —— 逐态那半跳过（单次全桩渲染照旧跑），因为裸键名判定要模块 ∪ 外壳两份字典',
+    );
+  }
 
   for (const pkg of modulePackages) {
     const name = pkg.manifest.name;
@@ -178,9 +356,44 @@ export async function run() {
       continue;
     }
 
+    const declared = pkg.manifest.dsh?.workbench?.card ?? null;
+    const declaresCard =
+      declared !== null && typeof declared.titleKey === 'string' && declared.titleKey !== '';
+
+    const shellClient = shellClientPathOf(pkg.dir);
+    const hasShell = shellClient !== undefined && existsSync(shellClient);
+    const current = { snapshot: SNAPSHOTS[0] };
+    let realKit;
+    let shellProblem;
+    if (hasShell && shellDictionaries !== undefined) {
+      try {
+        realKit = shellKitOf(shellClient, { react: fakeReact(), dshPackage: fakeDshPackage() });
+      } catch (error) {
+        shellProblem = error instanceof Error ? error.message : String(error);
+      }
+    }
+
+    const makeKit = () => {
+      if (realKit === undefined) return fakeKit();
+      const hooks = { ...(realKit.hooks ?? {}) };
+      hooks.useApiResource = () => current.snapshot.resource;
+      // 闸这一格的默认（P1 五态都是它）：没查过 ⇒ capability null、gated true。快照带了
+      // `capability` 才换成那一份，`gated` 照 `gateOf(capability, 'capability')` 算 —— 判据不当
+      // 第二份真相：状态的语义归外壳，这里只是把"外壳会给的那一格"摆出来。
+      hooks.useCapabilityGate = (unit) => {
+        const capability = current.snapshot.capability?.(unit) ?? null;
+        return {
+          capability,
+          gated: capability === null || capability.status === 'ok' || capability.status === 'unchecked',
+          forceProbe: () => {},
+        };
+      };
+      return { ...realKit, hooks };
+    };
+
     let face;
     try {
-      const loaded = loadFace(clientFile);
+      const loaded = loadFace(clientFile, makeKit);
       face = loaded.exports;
     } catch (error) {
       problems.push(`${name}: 产物加载不起来 —— ${error.message}`);
@@ -218,12 +431,6 @@ export async function run() {
     }
 
     const card = registered?.card;
-    // 清单说"没有卡片"（`"card": null`）与产物说"没有卡片"必须是同一件事 —— 两处说法不一致就是
-    // 声明与代码打架：登记了的那张卡没人会画（外壳只认清单），它只会一直烂在产物里。
-    // 这条判据的名字就是它防的事：gitops 当初为了哄旧判据挂了一张"我这张卡片就是说我没有卡片"的占位卡。
-    const declared = pkg.manifest.dsh?.workbench?.card ?? null;
-    const declaresCard =
-      declared !== null && typeof declared.titleKey === 'string' && declared.titleKey !== '';
     if (!declaresCard) {
       if (typeof card === 'function') {
         problems.push(
@@ -240,9 +447,6 @@ export async function run() {
       continue;
     }
 
-    // 清单的 `card.titleKey` 是**面板那一格的标题**，它的文案住在模块自己交的字典里
-    // （`registerUnit` 那个面的 `messages`，`zh` / `en` 都必填）。键拼错、或字典漏了那一条 ⇒
-    // 面板上显示的就是原始键名（`demo.cardTitle`），而且一声不响 —— 这条判据盯它。
     const titleKey = pkg.manifest.dsh?.workbench?.card?.titleKey;
     if (typeof titleKey === 'string' && titleKey !== '') {
       const messages = registered?.messages;
@@ -263,7 +467,7 @@ export async function run() {
     }
 
     const props = {
-      world: { current: {} },
+      world: { current: { sessionId: null, workspace: null } },
       t: (key) => key,
       refreshToken: 0,
       onRefresh: () => {},
@@ -272,49 +476,154 @@ export async function run() {
       onSummary: () => {},
     };
 
-    let tree;
-    try {
-      tree = card(props);
-    } catch (error) {
-      problems.push(`${name}: 空数据下卡片抛了 —— ${error.message}`);
+    if (realKit === undefined) {
+      const why =
+        shellProblem !== undefined
+          ? `取不出这份外壳的 kit（${shellClient}）—— ${shellProblem}`
+          : shellDictionaries === undefined
+            ? '取不出 @dsh-workbench/shared 的字典'
+            : '没装外壳（@dsh-workbench/core）';
+      let tree;
+      try {
+        tree = card(props);
+      } catch (error) {
+        problems.push(`${name}: 空数据下卡片抛了 —— ${error.message}`);
+        continue;
+      }
+      if (tree === null || tree === undefined) {
+        problems.push(`${name}: 空数据下卡片返回空（界面上就是一片空白）`);
+        continue;
+      }
+      const budget = { left: 20000, maxDepth: 0, classNames: new Set(), stubs: new Set(), texts: [] };
+      let count;
+      try {
+        count = render(tree, 0, budget);
+      } catch (error) {
+        const where = (error.stack ?? '').split('\n').slice(1, 4).join(' | ');
+        problems.push(`${name}: 卡片体内的组件抛了 —— ${error.message}\n      ${where}`);
+        continue;
+      }
+      if (count <= 1) {
+        problems.push(`${name}: 卡片只画出一个节点 —— 卡片体没跑（或什么都没画）`);
+        continue;
+      }
+      if (!(budget.classNames.has('wb-card') || budget.stubs.has('Card'))) {
+        problems.push(
+          `${name}: 卡片没套外壳的卡壳 —— 用 kit.components.Card（推荐），或自己写契约类 wb-card + ` +
+            `wb-cardBody；裸内容在面板里看起来就"不是一张卡片"`,
+        );
+        continue;
+      }
+      footnotes.push(`${name}: ${why} —— 逐态渲染跳过，只跑了单次全桩渲染`);
+      rows.push(`${name}: 空数据下画得出 ${count} 个节点（最深 ${budget.maxDepth} 层）`);
+      degraded += 1;
       continue;
     }
 
-    if (tree === null || tree === undefined) {
-      problems.push(`${name}: 空数据下卡片返回空（界面上就是一片空白）`);
-      continue;
-    }
+    const missing = [];
+    const counts = new Map();
+    const textsBySnapshot = new Map();
+    const classNames = new Set();
+    const stubs = new Set();
 
-    const budget = { left: 20000, maxDepth: 0, classNames: new Set(), stubs: new Set() };
-    let count;
-    try {
-      count = render(tree, 0, budget);
-    } catch (error) {
-      const where = (error.stack ?? '').split('\n').slice(1, 4).join(' | ');
-      problems.push(`${name}: 卡片体内的组件抛了 —— ${error.message}\n      ${where}`);
-      continue;
+    for (const snapshot of SNAPSHOTS) {
+      current.snapshot = snapshot;
+      counts.set(snapshot.name, []);
+      for (const language of LANGUAGES) {
+        const budget = { left: 20000, maxDepth: 0, classNames: new Set(), stubs: new Set(), texts: [] };
+        const where = `${snapshot.name}（${language}）`;
+        props.t = translatorOf(
+          language,
+          registered?.messages,
+          shellDictionaries,
+          missing,
+          snapshot.name,
+        );
+        props.world = { current: { sessionId: null, workspace: snapshot.workspace } };
+
+        let tree;
+        try {
+          tree = card(props);
+        } catch (error) {
+          problems.push(`${name}: ${where} 卡片抛了 —— ${error.message}`);
+          continue;
+        }
+        if (tree === null || tree === undefined) {
+          problems.push(`${name}: ${where} 卡片返回空 —— 这一态下卡片没画出来（界面上就是一片空白）`);
+          continue;
+        }
+        let count;
+        try {
+          count = render(tree, 0, budget);
+        } catch (error) {
+          const stack = (error.stack ?? '').split('\n').slice(1, 4).join(' | ');
+          problems.push(`${name}: ${where} 卡片体内的组件抛了 —— ${error.message}\n      ${stack}`);
+          continue;
+        }
+        if (count <= 1) {
+          problems.push(
+            `${name}: ${where} 卡片只画出 ${count} 个节点 —— 这一态下卡片体没跑（或只剩一层空壳）`,
+          );
+          continue;
+        }
+        counts.get(snapshot.name).push(count);
+        for (const one of budget.classNames) classNames.add(one);
+        for (const one of budget.stubs) stubs.add(one);
+        const bucket = textsBySnapshot.get(snapshot.name) ?? [];
+        bucket.push(...budget.texts);
+        textsBySnapshot.set(snapshot.name, bucket);
+        for (const hit of forbiddenHitsOf(budget.texts)) {
+          problems.push(
+            `${name}: ${where} 屏上出现了 ${hit.token} —— 这一态下卡片把它摆到了文字上。` +
+              `命中的那串：${hit.text.slice(0, 120)}`,
+          );
+        }
+      }
     }
-    if (count <= 1) {
-      problems.push(`${name}: 卡片只画出一个节点 —— 卡片体没跑（或什么都没画）`);
-      continue;
+
+    if (missing.length > 0) {
+      const grouped = new Map();
+      for (const one of missing) {
+        const key = `${one.language}\u0000${one.key}`;
+        if (!grouped.has(key)) grouped.set(key, { key: one.key, language: one.language, snapshots: [] });
+        const entry = grouped.get(key);
+        if (!entry.snapshots.includes(one.snapshot)) entry.snapshots.push(one.snapshot);
+      }
+      for (const entry of grouped.values()) {
+        problems.push(
+          `${name}: t('${entry.key}') 在 ${entry.language} 里没有落点（问它的快照：` +
+            `${entry.snapshots.join('、')}）—— 屏上会显示原始键名。` +
+            '命中判定 = 模块 messages ∪ 外壳 dictionaries',
+        );
+      }
     }
-    // 卡片得**套上外壳给的卡壳**：要么用 `kit.components.Card` 这个组件（推荐、也是 hello 现在的做法），
-    // 要么自己写契约类 `wb-card`（`board.css` 里那条，兄弟模块现在还是这么写的）。
-    //
-    // 用户实测（2026-10-09）："我们的 hello module 怎么不是卡片" —— 面板里那块内容既没有底色也没有
-    // 描边，看着就是标题加一段话。原因是卡片函数没套壳：当时用的是 `wb-view`（那是面板列布局），
-    // 更早那份装进 profile 的产物还自己搓过 `wb-hello*`。两种都查得出来：组件走 stub 名，类名走 classNames。
-    const shelled = budget.classNames.has('wb-card') || budget.stubs.has('Card');
-    if (!shelled) {
+
+    if (!(classNames.has('wb-card') || stubs.has('Card'))) {
       problems.push(
         `${name}: 卡片没套外壳的卡壳 —— 用 kit.components.Card（推荐），或自己写契约类 wb-card + ` +
           `wb-cardBody；裸内容在面板里看起来就"不是一张卡片"`,
       );
       continue;
     }
-    rows.push(`${name}: 空数据下画得出 ${count} 个节点（最深 ${budget.maxDepth} 层）`);
+
+    const per = SNAPSHOTS.map(
+      (snapshot) => `${snapshot.name} ${counts.get(snapshot.name).join('/') || '—'}`,
+    ).join(' · ');
+    rows.push(`${name}: ${SNAPSHOTS.length} 态 × zh/en 都画得出 —— ${per} 个节点`);
+
+    const shapes = new Set(
+      SNAPSHOTS.map((snapshot) => [...new Set(textsBySnapshot.get(snapshot.name) ?? [])].sort().join('\n')),
+    );
+    if (shapes.size === 1) {
+      footnotes.push(
+        `${name}: ${SNAPSHOTS.length} 个快照渲染出来的文本完全一样 —— 不判红，只当线索：它的取数可能没走 ` +
+          'kit.hooks.useApiResource，或这张卡片本来就不随态分叉',
+      );
+    }
   }
 
+  const shellClients = shellDictionaries === undefined ? [] : shellClientsOf(modulePackages);
+
   if (problems.length > 0) {
     return { status: 'fail', notes: [], problems };
   }
@@ -328,9 +637,19 @@ export async function run() {
   return {
     status: 'pass',
     notes: [
-      `${rows.length} 个模块过了卡片这一关：有卡片的都在**空数据**下画得出来（不许抛）、清单的 titleKey 在字典里都有落点；` +
-        '清单写 "card": null 的，产物里也确实没登记卡片（声明与代码同一句话）',
+      `${rows.length} 个模块过了卡片这一关：` +
+        (degraded === 0
+          ? `${SNAPSHOTS.length} 态 × zh/en 各渲染一遍`
+          : `逐态那半这次有 ${degraded} 个模块跳过（没装外壳 / 取不出外壳，见下），其余 ${SNAPSHOTS.length} 态 × zh/en 各渲染一遍`) +
+        ' —— 不抛、非空白、文字里没有 ' +
+        'undefined / NaN / [object Object] / null、没有裸键名、套了外壳的卡壳、清单的 titleKey 在两语字典里都有落点。' +
+        `（断言的是"${SNAPSHOTS.length} 种外壳侧输入下都退化得漂亮"，不是"画的是哪一态那一屏" —— 屏的对错归模块自己的 ` +
+        'card-states.test.ts 与 design.json 状态矩阵）',
+      ...(shellClients.length === 0
+        ? []
+        : [`逐态用的真壳（模块仓里装的那份 client.js）：${shellClients.join('、')}`]),
       ...rows,
+      ...footnotes,
     ],
     problems: [],
   };