@dsh-workbench/module-tools 0.3.2 → 0.3.4

package/src/shell-type-files.mjs

@@ -0,0 +1,103 @@
+// kit 成员 → 类型文件：外壳那两个包的类型树（`@dsh-workbench/shared` 的 `dist` 与外壳自己的 `dist/types`）。
+//
+// 为什么要扫：kit 的成员是**运行期**从外壳产物 `client.js` 里跑出来的（见 `checks/kit.mjs`），
+// 产物里没有"这个成员来自哪个模块"；而类型树里每个成员的声明都躺在某份 `.d.ts` 里 ——
+// 扫一遍就能把"名字"落到"文件"，于是 agent「想问哪个直接去看那份文件」有确切路径。
+//
+// 为什么是名字扫描而不是真正的类型解析：这些 `.d.ts` 是 tsc 生成的、声明形状规整
+// （`export declare const X` / `export interface X` / `export { X } from '…'`），而 kit 的成员
+// 本来就是运行期对象上的键名。扫描不引 TypeScript 依赖、贵在稳；代价是"同名声明出现在多处"时
+// 要挑一个（挑法见 `preferred`），以及极少数成员指到的是 barrel 而不是最终实现文件。
+// 实测本机 190 个 kit 成员 190 个都落得到文件（见 `.scratch/dsh-primitives-face/verify.md` §2）。
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+
+const PATTERNS = [
+  /^export declare (?:const|function|class) (\w+)/gm,
+  /^export (?:interface|type) (\w+)/gm,
+  /^export \{([^}]*)\}/gm,
+  /^declare (?:const|function|class) (\w+)/gm,
+  /^(?:interface|type) (\w+)/gm,
+];
+
+function walk(dir, acc = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, acc);
+    else if (full.endsWith('.d.ts')) acc.push(full);
+  }
+  return acc;
+}
+
+function namesIn(clause) {
+  if (!clause.includes(',') && !clause.includes(' ')) return [clause];
+  return clause
+    .split(',')
+    .map((raw) => raw.trim().split(/\s+as\s+/).pop().trim())
+    .filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
+}
+
+/** 外壳那两个包的类型树（`shared` 没装就只给外壳那棵）。 */
+export function shellTypeRoots(shellClientPath) {
+  const shellRoot = dirname(shellClientPath);
+  const roots = {};
+  const shellTypes = join(shellRoot, 'dist', 'types');
+  if (existsSync(shellTypes)) roots.shell = shellTypes;
+  // 打印用"从 node_modules 看"的那条路径（pnpm 的真身在 `.pnpm/` 哈希目录里）；读文件两条都行。
+  const viaNodeModules = join(shellRoot, 'node_modules', '@dsh-workbench', 'shared', 'dist');
+  try {
+    // 解析 "." 那个入口（= `dist/index.js`）再取 dirname —— shared 的 `exports` 里**没有**
+    // `./package.json` 这一条，直接 resolve 它的 package.json 会 ERR_PACKAGE_PATH_NOT_EXPORTED。
+    const sharedEntry = createRequire(join(shellRoot, 'package.json')).resolve('@dsh-workbench/shared');
+    const sharedTypes = dirname(sharedEntry);
+    if (existsSync(sharedTypes)) roots.shared = existsSync(viaNodeModules) ? viaNodeModules : sharedTypes;
+  } catch {
+    // 没装 shared：只有外壳自己那棵，仍然能落一部分成员
+  }
+  return { shellRoot, roots };
+}
+
+/** 同名多处时挑哪个：组件 > hooks > 库 > 其他，同档挑路径短的。 */
+function preferred(candidates) {
+  const rank = (file) =>
+    file.includes('/components/') ? 0 : file.includes('/hooks/') ? 1 : file.includes('/lib/') ? 2 : 3;
+  return [...candidates].sort((a, b) => rank(a.file) - rank(b.file) || a.file.length - b.file.length)[0];
+}
+
+/**
+ * 把 kit 的成员名落到类型文件。
+ * 返回 `{ roots, files: Map<名字, 绝对路径>, missing: 名字[] }` —— `roots` 是两棵类型树的绝对根。
+ */
+export function memberFilesOf(shellClientPath, names) {
+  const { roots } = shellTypeRoots(shellClientPath);
+  const index = new Map();
+  for (const root of Object.values(roots)) {
+    for (const file of walk(root)) {
+      let text;
+      try {
+        text = readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      for (const pattern of PATTERNS) {
+        for (const match of text.matchAll(pattern)) {
+          for (const name of namesIn(match[1])) {
+            if (!index.has(name)) index.set(name, []);
+            const found = index.get(name);
+            if (!found.some((one) => one.file === file)) found.push({ file });
+          }
+        }
+      }
+    }
+  }
+  const files = new Map();
+  const missing = [];
+  for (const name of names) {
+    const candidates = index.get(name);
+    if (candidates === undefined || candidates.length === 0) missing.push(name);
+    else files.set(name, preferred(candidates).file);
+  }
+  return { roots, files, missing };
+}

package/template/README.md.tpl

@@ -4,19 +4,34 @@
 
 ```bash
 dsh-wb-module build     # 出 dist/host.js 与套了 loader 壳的 client.js
-dsh-wb-module check     # 契约 / 产物边界 / 源码边界 / dsh 原语 / kit 面 / 卡片渲染 / 独立构建 / 内部标识 / 样式归属 / 不指外壳
-dsh-wb-module check --only cards   # 十条可以单跑
+dsh-wb-module check     # 契约 / 声明协议 / 产物边界 / 源码边界 / 架构 / dsh 原语 / kit 面 / 卡片渲染 / 独立构建 / 内部标识 / 样式归属 / 不指外壳 / 代码卫生（eslint）
+dsh-wb-module check --only cards   # 十三条可以单跑
 ```
 
-包自带的四个脚本（`check` 的契约判据要求它们都在）：
+包自带的六个脚本（`build` / `typecheck` / `test` / `selfcheck` 是 `check` 的契约判据要求的那四个；`check` 跑全部判据，`lint` 只跑源码卫生那一条）：
 
 ```bash
 pnpm build        # 构建产物
 pnpm typecheck    # tsc --noEmit
 pnpm test         # vitest（src/**/*.test.ts）
 pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍，看卡片真进没进外壳
+pnpm check        # dsh-wb-module check
+pnpm lint         # dsh-wb-module lint（`--fix` 就地改文件；`check` 永不动手）
 ```
 
+形状是**分层多文件**：`src/components/HelloCard.tsx` 是这张卡（卡壳 + 两句正文），
+`src/client.tsx` 只剩面（注册 + 把 props 交给组件），`src/host.ts` 是宿主面，
+`src/messages.ts` 是文案。目录**按需要出现** —— 这份没有纯逻辑，所以没有 `src/model/`；
+一旦有了（换算 / 状态机 / 类型），就放 `src/model/**` 并配一份同目录测试。
+两个面在第 10 层、`components/` 第 2 层、`model/` 与 `messages.ts` 第 1 层：
+上层只许 import 下层的，`arch.config.mjs` 那份方言 + `check` 的 `arch` 判据会当场报
+（宿主侧 import `components/**` 是跨运行时，也红）。
+
+包根还有两份**只有两行**的方言配置，各自一条判据按"文件在不在"上车：
+`arch.config.mjs`（`moduleArch()`：层序 / 反向依赖 / 跨运行时）与
+`eslint.config.mjs`（`moduleLint()`：`console` / `as any` / hooks 那几条 / 手搓颜色字面量）；
+要开口子都从工厂参数进，别手写一份自己的配置。
+
 装进本地工作台：
 
 ```bash

package/template/arch.config.mjs

@@ -0,0 +1,2 @@
+import { moduleArch } from '@dsh-workbench/module-tools/arch';
+export default moduleArch();

package/template/eslint.config.mjs

@@ -0,0 +1,2 @@
+import { moduleLint } from '@dsh-workbench/module-tools/lint';
+export default moduleLint({ rootDir: import.meta.dirname });

package/template/package.json.tpl

@@ -14,6 +14,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "selfcheck": "dsh-wb-module build && node scripts/smoke.mjs",
+    "check": "dsh-wb-module check",
+    "lint": "dsh-wb-module lint",
     "prepack": "dsh-wb-module build"
   },
   "dsh": {
@@ -21,7 +23,7 @@
     "client": {
       "platform": "web",
       "inject": ["@dsh-workbench/core"],
-      "external": ["@dsh-workbench/core/client"]
+      "external": ["@dsh-workbench/core/client", "@deepseek-ai/dsh-client-ui-primitives"]
     },
     "workbench": {
       "apiVersion": 1,
@@ -35,6 +37,7 @@
   "peerDependencies": { "@dsh-workbench/core": "__SHELL_RANGE__", "react": "*" },
   "peerDependenciesMeta": { "react": { "optional": true } },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-primitives": "__DSH_UI_VERSION__",
     "@dsh-workbench/core": "__SHELL_RANGE__",
     "@dsh-workbench/module-tools": "__SHELL_RANGE__",
     "@types/node": "^24.19.0",

package/template/src/client.tsx.tpl

@@ -1,16 +1,15 @@
-import { createElement as h } from 'react';
-import { kit } from '@dsh-workbench/core/client';
+import type { ReactElement } from 'react';
+import { HelloCard } from './components/HelloCard';
 import { messages } from './messages';
 
 const UNIT_ID = '__UNIT__';
 
-type Rendered = ReturnType<typeof h>;
 type Translate = (key: string, params?: Record<string, unknown>) => string;
 
 interface UnitClientFace {
   readonly unit: string;
   readonly messages: { readonly zh: Readonly<Record<string, string>>; readonly en: Readonly<Record<string, string>> };
-  readonly card: (props: { readonly t: Translate; readonly onRefresh: () => void }) => Rendered;
+  readonly card: (props: { readonly t: Translate; readonly onRefresh: () => void }) => ReactElement;
 }
 
 interface UnitClientApi {
@@ -25,20 +24,7 @@ interface ClientContext {
 const face: UnitClientFace = {
   unit: UNIT_ID,
   messages,
-  card: (props) => {
-    const { Card } = kit.components;
-    return h(
-      Card,
-      {
-        t: props.t,
-        title: props.t(`${UNIT_ID}.cardTitle`),
-        refreshing: false,
-        onRefresh: props.onRefresh,
-      },
-      h('p', null, props.t(`${UNIT_ID}.heading`)),
-      h('p', null, props.t(`${UNIT_ID}.body`)),
-    );
-  },
+  card: (props) => HelloCard({ t: props.t, onRefresh: props.onRefresh }),
 };
 
 export const inject = ['workbenchUnits'];

package/template/src/components/HelloCard.tsx.tpl

@@ -0,0 +1,28 @@
+import { createElement as h } from 'react';
+import { kit } from '@dsh-workbench/core/client';
+
+const UNIT_ID = '__UNIT__';
+
+const { Card } = kit.components;
+
+type Rendered = ReturnType<typeof h>;
+type Translate = (key: string, params?: Record<string, unknown>) => string;
+
+export interface HelloCardProps {
+  readonly t: Translate;
+  readonly onRefresh: () => void;
+}
+
+export function HelloCard(props: HelloCardProps): Rendered {
+  return h(
+    Card,
+    {
+      t: props.t,
+      title: props.t(`${UNIT_ID}.cardTitle`),
+      refreshing: false,
+      onRefresh: props.onRefresh,
+    },
+    h('p', null, props.t(`${UNIT_ID}.heading`)),
+    h('p', null, props.t(`${UNIT_ID}.body`)),
+  );
+}

package/template-diy/README.md.tpl

@@ -8,22 +8,24 @@
 ```bash
 dsh-wb-module init <unit> --dir <目录> --template diy   # 生成这份骨架（默认模板是没有数据源的空壳）
 dsh-wb-module build     # 出 dist/host.js 与套了 loader 壳的 client.js
-dsh-wb-module check     # 十条判据：契约 / 产物边界 / 源码边界 / dsh 原语 / kit 面 / 卡片渲染 / 独立构建 / 内部标识 / 样式归属 / 不指外壳
-dsh-wb-module check --only cards   # 十条可以单跑
+dsh-wb-module check     # 十三条判据：契约 / 声明协议 / 产物边界 / 源码边界 / 架构 / dsh 原语 / kit 面 / 卡片渲染 / 独立构建 / 内部标识 / 样式归属 / 不指外壳 / 代码卫生（eslint）
+dsh-wb-module check --only cards   # 十三条可以单跑
 ```
 
-包自带的四个脚本（`check` 的契约判据要求它们都在）：
+包自带的六个脚本（`build` / `typecheck` / `test` / `selfcheck` 是 `check` 的契约判据要求的那四个；`check` 跑全部判据，`lint` 只跑源码卫生那一条）：
 
 ```bash
 pnpm build        # 构建产物
 pnpm typecheck    # tsc --noEmit
 pnpm test         # vitest：路由真读数 + 卡片五态
 pnpm selfcheck    # 构建 + 把 client.js 当浏览器加载器跑一遍 + 调一次 <unit>/overview 看它真读盘
+pnpm check        # dsh-wb-module check
+pnpm lint         # dsh-wb-module lint（`--fix` 就地改文件；`check` 永不动手）
 ```
 
-## 需求底稿（做之前填，做完对着它验收）
+## 需求底稿（做之前填，做完自己逐条走一遍）
 
-三张表既是**要问清的需求**，也是**最后的验收单** —— 表里每一格都要能在界面上见过或点过。
+三张表既是**要问清的需求**，也是**最后的验收单** —— 表里每一格 agent 都要在真卡片上见过或点过。
 **空着的格就是还没定的事**，别带着空格往下做：落点是同目录的 `design.json`
 （`dsh-wb-module design check` 会把空格一格一格列出来），**下面标了 start/end 的那一段就是由它生成的**
 —— 要改三张表就改 `design.json`，再 `dsh-wb-module design render`；手改那一段会被 next 一次 check 判红。
@@ -86,17 +88,28 @@ 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` 壳 + 五态（待机 / 加载 / 就绪 / 出错，其中"就绪但空"单列一态） |
-| `src/messages.ts` | 卡片那几句文案（zh / en） |
-| `src/plugin.test.ts` | 面注册 + 路由真读 + 五态的断言 |
-| `scripts/smoke.mjs` | 接线自检：卡片进没进外壳、路由真读没真读 |
-| `tsconfig.json` / `vitest.config.ts` / `types/globals.d.ts` | 经典 JSX 运行时（`jsxFactory: h`）、vitest 的别名、浏览器半侧的运行时垫片 |
-| `README.md` | 就是本文 |
+**分层多文件**，不是单文件：数字越小越底层，上层只许 import 下层的（`arch.config.mjs` 那条
+`arch` 判据盯着，`dsh-wb-module check` 会跑）。目录**按需要出现**：这份有状态逻辑，所以有 `model/`。
+
+| 文件 | 是什么 | 层 |
+|---|---|---|
+| `package.json` | 自述清单：`dsh.workbench.unit` = `__UNIT__`、两个面（`src/host.ts` / `src/client.tsx`）、六个脚本、peer 下限 | — |
+| `arch.config.mjs` | 本模块的架构方言，**只有两行**（`import { moduleArch }` + `export default moduleArch()`）—— 层序表 / 两个运行时 / 阈值只有 `@dsh-workbench/module-tools/arch` 那一份，随工具链同代 | — |
+| `eslint.config.mjs` | 本模块的**语法卫生方言**，同样两行：`moduleLint()` —— 规则表只有 `@dsh-workbench/module-tools/lint` 那一份（`console` / `as any` / hooks 那几条 / 手搓颜色与 `!important`）；要开口子就 `moduleLint({ rules })` | — |
+| `cordis.patch.yml` | 插进 dsh 组合的补丁 | — |
+| `design.json` | 三张表 + 状态矩阵 + 数据源记录 + 验收清单（**唯一真相**，上面那段由它生成；`dsh-wb-module design check/render/accept` 读写它） | — |
+| `src/model/overview.ts` | 纯逻辑：类型 + 五态状态机 + `formatBytes`。两个运行时都读得到，不碰 react / kit / dsh / `node:*` | 1 |
+| `src/model/overview.test.ts` | 模型层的配对测试（有 `src/model/**` 就必须有 —— `arch` 的 M08） | 99 |
+| `src/messages.ts` | 卡片那几句文案（zh / en），键带 `<unit>.` 前缀 | 1 |
+| `src/components/OverviewCard.tsx` | 卡片：`Card` 壳 + 五态（待机 / 加载 / 就绪 / 出错，其中"就绪但空"单列一态）+ 最大的几个文件 | 2 |
+| `src/components/OverviewCard.module.css` | 这个组件自己的样式（CSS Modules，构建时类名按路径哈希）—— **样式跟组件同目录** | 2 |
+| `src/components/OverviewCard.test.ts` | 这张卡五态各画得出来（测试跟着被测的东西住） | 99 |
+| `src/host.ts` | 宿主面：`readOverview()`（真读目录）+ 一条只读路由 `<unit>/overview`；类型从 `./model/overview` 引 | 10 |
+| `src/client.tsx` | 浏览器面：**只剩面** —— 注册 + 把 props 交给 `components/OverviewCard` | 10 |
+| `src/plugin.test.ts` | 面注册 + 路由真读的断言 | 99 |
+| `scripts/smoke.mjs` | 接线自检：卡片进没进外壳、路由真读没真读 | — |
+| `tsconfig.json` / `vitest.config.ts` / `types/globals.d.ts` / `types/styles.d.ts` | 经典 JSX 运行时（`jsxFactory: h`）、vitest 的别名、浏览器半侧的运行时垫片、`*.module.css` 的类名表声明 | — |
+| `README.md` | 就是本文 | — |
 
 ## 数据是在哪算出来的
 
@@ -227,8 +240,9 @@ env: {
 
 ## 卡片画哪五态
 
-`src/client.tsx` 的 `overviewStateOf({ phase, value, error })` 是一条纯函数，
-每个分支各对应一屏（`src/plugin.test.ts` 一屏一屏断言）：
+`src/model/overview.ts` 的 `overviewStateOf({ phase, value, error })` 是一条纯函数，
+每个分支各对应一屏（`src/model/overview.test.ts` 直接断言这条函数，
+`src/components/OverviewCard.test.ts` 再把每一屏画一遍）：
 
 | 态 | 什么时候 | 画什么 |
 |---|---|---|
@@ -254,13 +268,24 @@ dsh plugin --profile workbench add <本目录>
   取了旧外壳没有的成员会在用户机器上首帧渲染就炸（peer 下限因此不许比 devDependency 旧）。
 * **两个运行时不许互引**：宿主侧不许碰 DOM / react，浏览器侧不许碰 `node:` / `process.env` / `Buffer`
   （`check:bundles` 对着产物查）。所以目录读在 `src/host.ts`，卡片只管画。
+  跨运行时那一条**层号拦不住**（`components/` 第 2 层、`host.ts` 第 10 层，"向下依赖"看着合法）——
+  是 `arch` 判据按面判的：`src/components/**` 整片算 client 面，宿主侧 import 它当场红。
+* **层序**：`src/model/**`（纯逻辑，第 1 层）谁都能读，但它**不碰** react / kit / dsh / `node:*`；
+  视图在 `src/components/**`（第 2 层），只许 import 第 1 层；两个面在第 10 层。
+  要加一层就在 `arch.config.mjs` 里明写（`moduleArch({ layers: … })`）—— 多出来的目录默认是 S01 红。
+* **语法卫生**（第十三条）：`eslint.config.mjs` 那份方言管 `console.log` / `as any` / 手搓颜色字面量 /
+  `!important` / hooks 那几条（`rules-of-hooks`、渲染期写 ref、漏依赖是 **error**，其余 recommended 是 **warn**）。
+  `check` 把 error 算红、`warn` 只计数；要动手就先 `dsh-wb-module lint --fix`（`check` 一个字节都不改）。
+  个别地方真要破例就在 `eslint.config.mjs` 里 `moduleLint({ rules })` 开口子，别悄悄换成手写配置
+  （判据按方言指纹认它）。
 * `@/` 只许指自己（`@/modules/__UNIT__/*`）；共享代码走包名；`@deepseek-ai/dsh-*` 只在客户端侧用，
   且必须同时写进 `package.json` 的 `dsh.client.external`。
 * **自己的样式走 CSS Modules**（`src/x.module.css` + `import styles from './x.module.css'`）：
   类名照常写就行 —— 构建会**按文件路径哈希**（跨模块不会撞），但**别带 `wb-` 前缀**：
   `wb-*` 是外壳的全局类名，模块定义它、或借契约里没有的那一个，`check:style` 都会判红。
   要借外壳契约里的类，写 `:global(.wb-…)`，而且那个类必须在契约里。
-  这份骨架没带样式文件：五态全用 kit 的组件，够看。
+  这份骨架带了一份最小的 `src/components/OverviewCard.module.css`（就一档列间距），
+  演示"样式与组件同目录"；`types/styles.d.ts` 是它给 `tsc` 的类名表声明（少了它 `styles.largest` 直接红）。
 * **源码零注释**（`src/**`）：要说的都写在这里。
 
 要发布：把 `package.json` 里的 `private` 去掉，并显式写上发布目标

package/template-diy/arch.config.mjs

@@ -0,0 +1,2 @@
+import { moduleArch } from '@dsh-workbench/module-tools/arch';
+export default moduleArch();

package/template-diy/design.json.tpl

@@ -29,6 +29,7 @@
     "timeout": "路径不存在 / 没权限 / 不是目录 → HTTP 200 + ok:false，码 overview-unreadable",
     "probeCommand": "node -e \"require('node:fs').readdirSync(process.cwd())\""
   },
+  "writes": [],
   "acceptance": [
     { "step": "打开面板 → 看到这张卡 → 路径 + N 文件 / M 目录 / 总字节", "checked": false },
     { "step": "换一个空目录 → 看到「这个目录是空的」（不是空白、也不是 0）", "checked": false },

package/template-diy/eslint.config.mjs

@@ -0,0 +1,2 @@
+import { moduleLint } from '@dsh-workbench/module-tools/lint';
+export default moduleLint({ rootDir: import.meta.dirname });

package/template-diy/package.json.tpl

@@ -14,6 +14,8 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "selfcheck": "dsh-wb-module build && dsh-wb-module design check && node scripts/smoke.mjs",
+    "check": "dsh-wb-module check",
+    "lint": "dsh-wb-module lint",
     "design": "dsh-wb-module design check",
     "prepack": "dsh-wb-module build"
   },
@@ -22,7 +24,7 @@
     "client": {
       "platform": "web",
       "inject": ["@dsh-workbench/core"],
-      "external": ["@dsh-workbench/core/client"]
+      "external": ["@dsh-workbench/core/client", "@deepseek-ai/dsh-client-ui-primitives"]
     },
     "workbench": {
       "apiVersion": 1,
@@ -36,6 +38,7 @@
   "peerDependencies": { "@dsh-workbench/core": "__SHELL_RANGE__", "react": "*" },
   "peerDependenciesMeta": { "react": { "optional": true } },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-primitives": "__DSH_UI_VERSION__",
     "@dsh-workbench/core": "__SHELL_RANGE__",
     "@dsh-workbench/module-tools": "__SHELL_RANGE__",
     "@types/node": "^24.19.0",

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

@@ -1,16 +1,9 @@
-import { createElement as h } from 'react';
-import { kit } from '@dsh-workbench/core/client';
+import type { ReactElement } from 'react';
+import { OverviewCard } from './components/OverviewCard';
 import { messages } from './messages';
 
 const UNIT_ID = '__UNIT__';
-const OVERVIEW_ROUTE = `${UNIT_ID}/overview`;
-const LIST_LIMIT = 5;
-const KB = 1024;
 
-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;
 
 interface WorkspaceView {
@@ -27,7 +20,7 @@ interface BoardProps {
 interface UnitClientFace {
   readonly unit: string;
   readonly messages: { readonly zh: Readonly<Record<string, string>>; readonly en: Readonly<Record<string, string>> };
-  readonly card: (props: BoardProps) => Rendered;
+  readonly card: (props: BoardProps) => ReactElement;
 }
 
 interface UnitClientApi {
@@ -39,148 +32,16 @@ interface ClientContext {
   effect(effect: () => void | (() => void), label?: string): () => void;
 }
 
-export interface OverviewFile {
-  readonly name: string;
-  readonly bytes: number;
-  readonly mtime: string;
-}
-
-export interface OverviewPayload {
-  readonly path: string;
-  readonly files: number;
-  readonly dirs: number;
-  readonly bytes: number;
-  readonly largest: readonly OverviewFile[];
-}
-
-type OverviewReady = { readonly ok: true } & OverviewPayload;
-
-interface Failure {
-  readonly code: string;
-  readonly message: string;
-}
-
-export type OverviewState =
-  | { readonly kind: 'idle' }
-  | { readonly kind: 'loading' }
-  | { readonly kind: 'ready'; readonly payload: OverviewPayload }
-  | { readonly kind: 'empty'; readonly payload: OverviewPayload }
-  | { readonly kind: 'error'; readonly detail: string };
-
-export interface OverviewInput {
-  readonly phase: 'idle' | 'loading' | 'ready' | 'error';
-  readonly value: OverviewReady | undefined;
-  readonly error: Failure | undefined;
-}
-
-export function formatBytes(bytes: number): string {
-  if (bytes < KB) return `${String(bytes)} B`;
-  if (bytes < KB * KB) return `${(bytes / KB).toFixed(1)} KB`;
-  if (bytes < KB * KB * KB) return `${(bytes / (KB * KB)).toFixed(1)} MB`;
-  return `${(bytes / (KB * KB * KB)).toFixed(1)} GB`;
-}
-
-function payloadState(payload: OverviewPayload): OverviewState {
-  const blank = payload.files === 0 && payload.dirs === 0;
-  return blank ? { kind: 'empty', payload } : { kind: 'ready', payload };
-}
-
-export function overviewStateOf(input: OverviewInput): OverviewState {
-  if (input.phase === 'idle') return { kind: 'idle' };
-  if (input.phase === 'error') {
-    const error = input.error;
-    return { kind: 'error', detail: error === undefined ? '' : `${error.code}: ${error.message}` };
-  }
-  if (input.value !== undefined && (input.phase === 'ready' || input.phase === 'loading')) {
-    return payloadState(input.value);
-  }
-  return { kind: 'loading' };
-}
-
-function bodyOf(state: OverviewState, t: Translate): Rendered {
-  if (state.kind === 'idle') {
-    return h(CenteredState, {
-      icon: null,
-      title: t(`${UNIT_ID}.needProject`),
-      compact: true,
-    });
-  }
-  if (state.kind === 'loading') {
-    return h(CenteredState, {
-      icon: null,
-      title: t(`${UNIT_ID}.loading`),
-      hint: t(`${UNIT_ID}.loadingHint`),
-      compact: true,
-    });
-  }
-  if (state.kind === 'error') {
-    return h(CenteredState, {
-      icon: null,
-      title: t(`${UNIT_ID}.errorTitle`),
-      detail: state.detail,
-      hint: t(`${UNIT_ID}.errorHint`),
-      compact: true,
-    });
-  }
-  if (state.kind === 'empty') {
-    return h(EmptyState, {
-      text: t(`${UNIT_ID}.empty`),
-      icon: h(IconPanelScreen, { size: 20 }),
-      compact: true,
-    });
-  }
-  const payload = state.payload;
-  return h(
-    StateBlock,
-    {
-      title: payload.path,
-      hint:
-        `${String(payload.files)}${t(`${UNIT_ID}.fileUnit`)} · ` +
-        `${String(payload.dirs)}${t(`${UNIT_ID}.dirUnit`)} · ${formatBytes(payload.bytes)}`,
-      resolving: t(`${UNIT_ID}.largest`),
-    },
-    h(
-      Rows,
-      null,
-      ...payload.largest.map((file) =>
-        h(Row, {
-          key: file.name,
-          label: file.name,
-          value: `${formatBytes(file.bytes)} · ${file.mtime}`,
-        }),
-      ),
-    ),
-  );
-}
-
 const face: UnitClientFace = {
   unit: UNIT_ID,
   messages,
-  card: (props) => {
-    const workspace = props.world.current.workspace;
-    const path = workspace?.path ?? '';
-    const resource = useApiResource<OverviewReady>(
-      OVERVIEW_ROUTE,
-      { path: path === '' ? undefined : path, limit: LIST_LIMIT },
-      props.refreshToken,
-      { enabled: path !== '' },
-    );
-    const state = overviewStateOf({
-      phase: resource.phase,
-      value: resource.value,
-      error: resource.error,
-    });
-    return h(
-      Card,
-      {
-        t: props.t,
-        title: props.t(`${UNIT_ID}.cardTitle`),
-        refreshing: resource.phase === 'loading',
-        onRefresh: props.onRefresh,
-      },
-      bodyOf(state, props.t),
-    );
-  },
+  card: (props) =>
+    OverviewCard({
+      path: props.world.current.workspace?.path ?? '',
+      refreshToken: props.refreshToken,
+      onRefresh: props.onRefresh,
+      t: props.t,
+    }),
 };
 
 export const inject = ['workbenchUnits'];

package/template-diy/src/components/OverviewCard.module.css.tpl

@@ -0,0 +1,5 @@
+.largest {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wb-len-8);
+}