@dsh-workbench/module-tools 0.1.2 → 0.1.4

package/package.json

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

package/src/build.mjs

@@ -3,11 +3,17 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { builtinModules } from 'node:module';
 import { join } from 'node:path';
 import { build as esbuild } from 'esbuild';
+import { SEED_SPECIFIERS } from './seed.mjs';
 
 const SHELL_CLIENT = '@dsh-workbench/core/client';
 const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.js', '.json'];
 const SINGLETON = /^@\/shared\/(hooks|components)\//;
 
+// dsh 的客户端模块表里"天生就有"的包（seed 词）。模块的浏览器产物**默认**把它们标成外部：
+// 这些是外壳那一份实例，内联进来就是第二份 —— 两份 React 组件树、两套样式、hover 与浮层失联。
+// 名单在 `../seed.mjs`（唯一真相）；判据侧由 `checks/source.mjs` 与 `checks/primitives.mjs` 守。
+const SEED_EXTERNAL = SEED_SPECIFIERS;
+
 function pickEntry(root, names) {
   for (const name of names) {
     const full = join(root, name);
@@ -84,7 +90,8 @@ export async function build({ root }) {
     platform: 'browser',
     format: 'cjs',
     target: 'es2022',
-    external: ['react', 'react-dom', SHELL_CLIENT, ...declared],
+    external: [SHELL_CLIENT, ...SEED_EXTERNAL, ...declared],
+    metafile: true,
     jsx: 'transform',
     jsxFactory: 'h',
     jsxFragment: 'Fragment',
@@ -94,6 +101,17 @@ export async function build({ root }) {
     logLevel: 'warning',
   });
 
+  // 物证：metafile 列出**这次真的被打进包里**的每个输入文件。dsh 的包只要出现，
+  // 就说明它没走外部化（声明漏了 / 名字写错 / 从 shared 内联进来）—— 那正是"第二份实例"。
+  // 不靠产物里的字符串去猜（tree-shaking 之后标记可能根本不进包），也不靠它自己报错。
+  const inlinedDsh = Object.keys(client.metafile.inputs).filter((path) => /@deepseek-ai[\\/]/.test(path));
+  if (inlinedDsh.length > 0) {
+    throw new Error(
+      `${id}: dsh 的包被打进了浏览器产物 —— ${inlinedDsh.join('、')}\n` +
+        '这些应当由外壳的模块表提供（标成 external 才是"用外壳那一份"）。见 ADR-0028。',
+    );
+  }
+
   const indented = client.outputFiles[0].text
     .split('\n')
     .map((line) => (line === '' ? line : `    ${line}`))

package/src/check.mjs

@@ -3,6 +3,7 @@ const CHECKS = {
   contracts: { title: '模块契约', load: () => import('./checks/contracts.mjs') },
   bundles: { title: '模块产物边界', load: () => import('./checks/bundles.mjs') },
   source: { title: '模块源码边界', load: () => import('./checks/source.mjs') },
+  primitives: { title: 'dsh 原语只从模块表拿', load: () => import('./checks/primitives.mjs') },
   cards: { title: '卡片渲染', load: () => import('./checks/cards.mjs') },
   standalone: { title: '独立构建', load: () => import('./checks/standalone.mjs') },
   markers: { title: '公开包无内部标识', load: () => import('./checks/markers.mjs') },

package/src/checks/cards.mjs

@@ -70,6 +70,19 @@ 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) {
   let captured;
   const fakeWindow = {
@@ -92,6 +105,7 @@ function loadFace(clientFile) {
   const fakeRequire = (id) => {
     if (id === 'react') return fakeReact();
     if (id === '@dsh-workbench/core/client') return { kit: fakeKit() };
+    if (id.startsWith('@deepseek-ai/')) return fakeDshPackage();
     throw new Error(`产物 require 了没桩的外部：${id}`);
   };
   const produced = captured.factory(fakeRequire);

package/src/checks/contracts.mjs

@@ -19,11 +19,12 @@ import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { discoverPackages } from '../discover.mjs';
+import { SEED_SHORT } from '../seed.mjs';
 
 const ROOT = process.env.DSH_WB_ROOT ?? fileURLToPath(new URL('../../../../', import.meta.url));
 
-/** dsh 浏览器侧的固定 seed 词表（模块表里天生就有的那几个）。 */
-const SEED = new Set(['react', 'react-dom', 'cordis', 'dsh-client-store', 'ui-slots', 'ui-primitives', 'ui-dockkit']);
+/** dsh 浏览器侧的固定 seed 词表（模块表里天生就有的那几个）—— 唯一真相在 `../seed.mjs`。 */
+const SEED = SEED_SHORT;
 
 const PLATFORMS = new Set(['web']);
 

package/src/checks/primitives.mjs

@@ -0,0 +1,116 @@
+// 模块用 dsh 的 UI 原语时，**只从模块表拿** —— 这条判据守的是"声明"与"产物"对不对得上。
+//
+// ADR-0028 决定：浏览器半侧直接用 dsh 的客户端 UI 原语（它们是平台种子词）。但"直接用"要付
+// 两笔账，任何一笔错了都不会当场报错，只会**悄悄多一份实例**或**等浏览器 require 那一刻才炸**：
+//
+//   ① 源码 import 了某个种子词 ⇒ 它必须出现在 `dsh.client.external` 里
+//      （漏声明 ⇒ 构建把那个包**内联**进模块产物 = 第二份 React 组件树、两套样式）；
+//   ② 同一条 ⇒ 产物 `client.js` 里必须有 `require("<说明符>")`
+//      （内联了就不会有 require —— 这是"到底外部化没有"唯一不靠猜的物证）；
+//   ③ 宿主产物里不许出现种子词的引用（那些包只在浏览器侧存在；宿主侧源码 import 它们
+//      由 `checks/source.mjs` 拦，这里对着产物再确认一次）。
+//
+// 判据跟着 `dsh.workbench` 自述清单走：没用 dsh 原语的模块直接跳过（0 命中 = 通过）。
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { discoverModulePackages } from '../discover.mjs';
+import { BROWSER_SEED_SPECIFIERS, SEED_SPECIFIERS } from '../seed.mjs';
+
+const IMPORT = /from\s*'([^']+)'|import\s*\(?\s*'([^']+)'/g;
+const SEED = new Set(SEED_SPECIFIERS);
+
+/** 短名写法（`ui-primitives`）也算声明过 —— 老包里有这种写法，不该因为写法短被判红。 */
+function declares(declared, specifier) {
+  if (declared.has(specifier)) return true;
+  const short = specifier.replace(/^@deepseek-ai\/(dsh-client-)?/, '');
+  return declared.has(short);
+}
+
+function sourceFiles(dir, acc = []) {
+  if (!existsSync(dir)) return acc;
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      if (entry === '__tests__' || entry === 'node_modules') continue;
+      sourceFiles(full, acc);
+    } else if (/\.tsx?$/.test(entry) && !/\.test\.tsx?$/.test(entry)) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+const problems = [];
+let modulesUsingPrimitives = 0;
+let modulesUsingReactOnly = 0;
+
+for (const pkg of discoverModulePackages({ root: process.cwd() })) {
+  const name = pkg.manifest.name;
+  const declared = new Set(pkg.manifest.dsh?.client?.external ?? []);
+  const used = new Map();
+
+  for (const file of sourceFiles(join(pkg.dir, 'src'))) {
+    const text = readFileSync(file, 'utf8');
+    for (const match of text.matchAll(IMPORT)) {
+      const specifier = match[1] ?? match[2];
+      if (specifier === undefined || !SEED.has(specifier)) continue;
+      if (!used.has(specifier)) used.set(specifier, relative(pkg.dir, file));
+    }
+  }
+  if (used.size === 0) continue;
+  const dshSeeds = [...used.keys()].filter((specifier) => BROWSER_SEED_SPECIFIERS.includes(specifier));
+  if (dshSeeds.length === 0) modulesUsingReactOnly += 1;
+  else modulesUsingPrimitives += 1;
+
+  // ① 只管 **dsh 的那些浏览器包**：react / react-dom 是构建一直默认外部化的（从第一天就是），
+  //    要求每个模块去声明它只会制造噪音。dsh 的包不一样 —— 旧版 module-tools 的默认表里没有它们。
+  const needsDeclaration = new Set(BROWSER_SEED_SPECIFIERS);
+  for (const [specifier, where] of used) {
+    if (needsDeclaration.has(specifier) && !declares(declared, specifier)) {
+      problems.push(
+        `${name}: ${where} 用了 ${specifier}，但 package.json 的 dsh.client.external 里没声明它 —— ` +
+          `漏声明会被构建内联进来（第二份实例）。加上 "${specifier}"`,
+      );
+    }
+  }
+
+  const client = join(pkg.dir, 'client.js');
+  if (!existsSync(client)) {
+    problems.push(`${name}: 源码用了 dsh 的种子词，但没有 client.js —— 先跑 dsh-wb-module build`);
+  } else {
+    const text = readFileSync(client, 'utf8');
+    for (const [specifier, where] of used) {
+      if (!text.includes(`require(${JSON.stringify(specifier)})`)) {
+        problems.push(
+          `${name}: ${where} 用了 ${specifier}，但产物 client.js 里没有 require("${specifier}") —— ` +
+            `它被**内联**进产物了（第二份实例）。检查 dsh.client.external 与构建用的 module-tools 版本`,
+        );
+      }
+    }
+  }
+
+  const host = join(pkg.dir, 'dist', 'host.js');
+  if (existsSync(host)) {
+    const text = readFileSync(host, 'utf8');
+    for (const specifier of BROWSER_SEED_SPECIFIERS) {
+      if (text.includes(`"${specifier}"`)) {
+        problems.push(
+          `${name}: 宿主产物 dist/host.js 里出现了 ${specifier} —— 那些包只在浏览器侧存在，` +
+            `宿主侧引用它就是起来那一刻炸`,
+        );
+      }
+    }
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`✖ dsh 原语 ${problems.length} 条不过：`);
+  for (const problem of problems) console.error(`  · ${problem}`);
+  process.exit(1);
+}
+
+console.log(
+  `✔ dsh 原语通过：${modulesUsingPrimitives} 个模块在用 dsh 的包（都声明了 external、产物里都是 ` +
+    `require、宿主产物里没有它们）· 另有 ${modulesUsingReactOnly} 个模块只用到 react/react-dom`,
+);

package/src/checks/source.mjs

@@ -2,15 +2,21 @@
 //
 // 外壳那份 `arch/rules/units.mjs` 是按**路径**发现套件的（`src/modules/<id>/unit.ts`），
 // 模块搬出 `src/` 之后它照跑但不报。那几条规则守的多是「外壳不许认识套件」——对模块包没意义；
-// 模块包自己要守的是另外四条，写在下面。判据全部来自源码里的 import 说明符，覆盖范围跟着
+// 模块包自己要守的是另外几条，写在下面。判据全部来自源码里的 import 说明符，覆盖范围跟着
 // `dsh.workbench` 自述清单走（新加模块不用改这里）。
+//
+// 关于 dsh 的包：「哪一半」**不靠目录名猜**，而是从两个入口（`faces.host` / `faces.client`）
+// 做一次本包内可达性分析。种子词（模块表里天生就有的那几个）在**只被客户端入口可达**的文件里
+// 可以用（ADR-0028）；宿主侧一个都不许碰 —— 那些包只在浏览器侧存在。
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { discoverModulePackages } from '../discover.mjs';
+import { isSeedSpecifier } from '../seed.mjs';
 
-
-const IMPORT = /from\s+'([^']+)'|import\s+'([^']+)'/g;
+// 静态 `from '…'`、副作用 `import '…'`、动态 `import('…')` —— 动态那条不能漏，
+// 模块入口常见写法是 `await import('./views/…')`，漏了就会把可达文件判成"死代码"。
+const IMPORT = /from\s*'([^']+)'|import\s*\(?\s*'([^']+)'/g;
 
 function sourceFiles(dir, acc = []) {
   for (const entry of readdirSync(dir)) {
@@ -25,6 +31,58 @@ function sourceFiles(dir, acc = []) {
   return acc;
 }
 
+/**
+ * 把一条 import 说明符解析成本包内的文件；解析不到就是包说明符（不外追）。
+ * 别名两条（与 `build.mjs` 的 aliasResolver 同一条约定）：
+ *   `@/modules/<unit>/X` → `src/X`   ·   `@/platforms/X` → `src/platforms/X`
+ */
+function resolveLocal(pkgDir, unit, fromFile, specifier) {
+  let base;
+  if (specifier.startsWith('@/')) {
+    const own = `@/modules/${unit}/`;
+    base = specifier.startsWith(own)
+      ? join(pkgDir, 'src', specifier.slice(own.length))
+      : join(pkgDir, 'src', specifier.slice(2));
+  } else if (specifier.startsWith('.')) {
+    base = resolve(dirname(fromFile), specifier);
+  } else {
+    return undefined;
+  }
+  const stems = [base, base.replace(/\.js$/, '')];
+  for (const stem of stems) {
+    for (const candidate of [
+      `${stem}.ts`,
+      `${stem}.tsx`,
+      join(stem, 'index.ts'),
+      join(stem, 'index.tsx'),
+    ]) {
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
+/** 从某个入口出发，本包内可达的源文件。 */
+function reachableFrom(pkgDir, unit, entry) {
+  const seen = new Set();
+  const start = join(pkgDir, entry);
+  if (!existsSync(start)) return seen;
+  const queue = [start];
+  while (queue.length > 0) {
+    const file = queue.pop();
+    if (seen.has(file)) continue;
+    seen.add(file);
+    const text = readFileSync(file, 'utf8');
+    for (const match of text.matchAll(IMPORT)) {
+      const specifier = match[1] ?? match[2];
+      if (specifier === undefined) continue;
+      const next = resolveLocal(pkgDir, unit, file, specifier);
+      if (next !== undefined && !seen.has(next)) queue.push(next);
+    }
+  }
+  return seen;
+}
+
 function hasPlatformPackage(manifest) {
   const names = Object.keys({ ...(manifest.dependencies ?? {}), ...(manifest.devDependencies ?? {}) });
   return names.some((name) => /(^|\/)platform-/.test(name));
@@ -34,10 +92,12 @@ const modulePackages = () => discoverModulePackages({ root: process.cwd() });
 
 const problems = [];
 let scanned = 0;
+let seedUsers = 0;
 
 for (const pkg of modulePackages()) {
   const name = pkg.manifest.name;
   const unit = pkg.manifest.dsh.workbench.unit;
+  const faces = pkg.manifest.dsh.workbench.faces ?? {};
   const srcDir = join(pkg.dir, 'src');
   const viaPlatform = hasPlatformPackage(pkg.manifest);
 
@@ -47,6 +107,17 @@ for (const pkg of modulePackages()) {
     );
   }
 
+  const hostReach = faces.host === undefined ? new Set() : reachableFrom(pkg.dir, unit, faces.host);
+  const clientReach = faces.client === undefined ? new Set() : reachableFrom(pkg.dir, unit, faces.client);
+  const sideOf = (file) => {
+    const host = hostReach.has(file);
+    const client = clientReach.has(file);
+    if (host && client) return 'both';
+    if (host) return 'host';
+    if (client) return 'client';
+    return 'orphan';
+  };
+
   for (const file of sourceFiles(srcDir)) {
     scanned += 1;
     const rel = relative(pkg.dir, file);
@@ -57,8 +128,27 @@ for (const pkg of modulePackages()) {
       if (specifier === undefined) continue;
 
       if (specifier.startsWith('@deepseek-ai/')) {
+        if (isSeedSpecifier(specifier) && sideOf(file) === 'client') {
+          seedUsers += 1;
+          continue;
+        }
+        if (isSeedSpecifier(specifier)) {
+          const side = sideOf(file);
+          const why =
+            side === 'both'
+              ? '这个文件**两个入口都到得了** —— 它会被拖进宿主产物'
+              : side === 'orphan'
+                ? '这个文件两个入口都到不了（可能是死代码），证明不了它只在客户端侧'
+                : '这个文件在宿主侧可达';
+          problems.push(
+            `${name}: ${rel} 里 import 了 ${specifier}（dsh 的浏览器包，是平台种子词）—— ${why}，` +
+              `而它只在浏览器侧存在。把它挪到只被 faces.client 可达的文件里`,
+          );
+          continue;
+        }
         problems.push(
-          `${name}: ${rel} 里 import 了 ${specifier} —— 平台契约要按需自己声明，不许直接吃 dsh 的包`,
+          `${name}: ${rel} 里 import 了 ${specifier} —— 它不是平台种子词，模块表里没有它，` +
+            `浏览器侧要用 dsh 的组件只能 import 种子词那几个（ADR-0028）；其余平台契约按需自己声明`,
         );
         continue;
       }
@@ -98,5 +188,7 @@ if (problems.length > 0) {
 }
 
 console.log(
-  `✔ 模块源码边界通过：${scanned} 个源文件 · 不吃平台包 · 不伸进外壳 app/ · 不跨模块 · 平台知识要么在自己包里、要么走平台包（不许两样都有）`,
+  `✔ 模块源码边界通过：${scanned} 个源文件 · 不伸进外壳 app/ · 不跨模块 · ` +
+    `平台知识要么在自己包里、要么走平台包（不许两样都有）· ` +
+    `dsh 的浏览器包只在客户端侧可用（${seedUsers} 处）`,
 );

package/src/checks/style.mjs

@@ -1,9 +1,14 @@
-import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { discoverModulePackages } from '../discover.mjs';
 
 const SHELL_SELECTOR = /(^|[\s,>+~])\.wb-[a-z0-9-]+/;
 const RULE = /\.wb-[a-z0-9-]+[^{}]*\{/;
+const CLASS_TOKEN = /(^|[^-\w])\.?(wb-[a-zA-Z0-9-]+)/g;
+const CONTRACT = fileURLToPath(
+  new URL('../../../workbench/src/shared/styles/board.css', import.meta.url),
+);
 
 function walk(dir, acc = []) {
   for (const entry of readdirSync(dir)) {
@@ -15,7 +20,18 @@ function walk(dir, acc = []) {
   return acc;
 }
 
+function isTestSource(file) {
+  return /(^|[\\/])__tests__[\\/]/.test(file) || /\.test\.[cm]?tsx?$/.test(file);
+}
+
+const contract = existsSync(CONTRACT)
+  ? new Set(
+      Array.from(readFileSync(CONTRACT, 'utf8').matchAll(CLASS_TOKEN), (match) => match[2]),
+    )
+  : null;
+
 const problems = [];
+const borrowed = [];
 const modules = discoverModulePackages({ root: process.cwd() });
 for (const pkg of modules) {
   for (const file of walk(pkg.dir)) {
@@ -26,7 +42,8 @@ for (const pkg of modules) {
     } catch {
       continue;
     }
-    text.split('\n').forEach((line, index) => {
+    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;
@@ -34,6 +51,20 @@ for (const pkg of modules) {
         `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 定义了外壳前缀的 CSS 规则 —— ${line.trim().slice(0, 100)}`,
       );
     });
+
+    if (contract === null || isTestSource(file)) continue;
+    if (!/\.tsx?$/.test(file)) continue;
+    lines.forEach((line, index) => {
+      for (const match of line.matchAll(CLASS_TOKEN)) {
+        const name = match[2];
+        if (line[match.index + match[0].indexOf(name) - 1] === '-') continue;
+        if (name.endsWith('-')) continue;
+        if (contract.has(name)) continue;
+        borrowed.push(
+          `${pkg.manifest.name}: ${relative(pkg.dir, file)}:${index + 1} 借用了 ${name}，契约里没有它 —— ${line.trim().slice(0, 100)}`,
+        );
+      }
+    });
   }
 }
 
@@ -43,4 +74,21 @@ if (problems.length > 0) {
   console.error('  （wb-* 是全局类名：两份同名规则按注入顺序互相覆盖，用户看到的是随机的那个）');
   process.exit(1);
 }
-console.log(`✔ 样式归属清楚：${modules.length} 个模块都没有定义外壳前缀（wb-*）的 CSS 规则`);
+
+if (borrowed.length > 0) {
+  console.error(`✖ 模块借用了契约里没有的 wb-* 类：${borrowed.length} 处`);
+  for (const one of borrowed) console.error(`  · ${one}`);
+  console.error(
+    '  （契约是本仓 board.css：模块只许借它里面有的类。没有的那个要么是拼错/改了名漏改，' +
+      '要么本该进 board.css —— 空类名在真机上就是没样式，而且没人会报错）',
+  );
+  process.exit(1);
+}
+
+const contractNote =
+  contract === null
+    ? '契约文件不在（这次只查了"模块不许定义 wb-*"）'
+    : `借用的类都在 board.css 契约里`;
+console.log(
+  `✔ 样式归属清楚：${modules.length} 个模块都没有定义外壳前缀（wb-*）的 CSS 规则；${contractNote}`,
+);

package/src/discover.mjs

@@ -1,5 +1,5 @@
 
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
 function manifestOf(dir) {
@@ -36,8 +36,11 @@ export function discoverPackages({ root = process.cwd() } = {}) {
   const seen = new Set();
   const found = [];
   for (const dir of dirs) {
-    if (seen.has(dir)) continue;
-    seen.add(dir);
+    // 按**真实路径**去重：`process.cwd()` 与 workspace 拼出来的路径可能是同一条目录的两种写法
+    // （软链，典型是 macOS 的 /tmp → /private/tmp），不规范化就会把同一个包扫两遍、报两遍。
+    const key = existsSync(dir) ? realpathSync(dir) : dir;
+    if (seen.has(key)) continue;
+    seen.add(key);
     const manifest = manifestOf(dir);
     if (manifest === undefined || typeof manifest.name !== 'string') continue;
     found.push({ dir, manifest });

package/src/seed.mjs

@@ -0,0 +1,45 @@
+// dsh 客户端模块表的**平台种子词** —— 一个模块的浏览器产物**天生**能 require 到它们。
+//
+// 名单真值出处：dsh 外壳构造种子表的地方（`@deepseek-ai/dsh-web-frontend` 的 dist，函数 WS()），
+// 证据与推理见 `.scratch/dsh-ui-alignment/spec.md` §0；「模块可以直接用它」的决定见 ADR-0028。
+//
+// 这份表是**唯一真相**：构建的 external 默认表（`build.mjs`）、契约判据（`contracts.mjs`）、
+// 源码边界（`checks/source.mjs`）与新增的原语判据（`checks/primitives.mjs`）都从这里取。
+// dsh 升版改了种子表，只改这一处。
+
+export const SEED_SPECIFIERS = [
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  '@deepseek-ai/cordis',
+  '@deepseek-ai/dsh-client-store',
+  '@deepseek-ai/dsh-client-ui-slots',
+  '@deepseek-ai/dsh-client-ui-primitives',
+  '@deepseek-ai/dsh-client-ui-dockkit',
+];
+
+/**
+ * 外部声明里允许的**短名**（历史写法：`"ui-primitives"` 这类）。
+ * 契约判据按它放行，免得老包只因为写法短就被判红。
+ */
+export const SEED_SHORT = new Set([
+  'react',
+  'react-dom',
+  'cordis',
+  'dsh-client-store',
+  'ui-slots',
+  'ui-primitives',
+  'ui-dockkit',
+  ...SEED_SPECIFIERS.filter((name) => name.startsWith('@deepseek-ai/dsh-client')),
+]);
+
+const SEED_LONG = new Set(SEED_SPECIFIERS);
+
+/** 是不是种子词（按完整说明符判断）。 */
+export const isSeedSpecifier = (specifier) => SEED_LONG.has(specifier);
+
+/** 种子词里那些 **dsh 的** 包 —— 它们只在浏览器侧存在，宿主侧一个都不许碰。 */
+export const BROWSER_SEED_SPECIFIERS = SEED_SPECIFIERS.filter(
+  (name) => name.startsWith('@deepseek-ai/'),
+);