@fps-games/vfx 0.1.1

package/tooling/validate-boundary.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// 库纯净契约(plan §17)的执行点:扫描库内所有 import,凡越过库边界 / 反向依赖项目 → 报违规。
+// 允许:@babylonjs/*、@fps/*、node: 内置、第三方裸包、库内相对路径(解析到库内存在的文件)。
+// 违规:相对路径解析后逃出库根或指向不存在的文件;命中项目模块特征(config/core/services/systems/gameplay/assets-index 等)。
+import { readdirSync, statSync, readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LIB_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+// 新包面 = packages/ 根的运行时 .ts + packages/effects/**(不含旧 Cocos 包 build.particle.* 等)
+const PKG_ROOT = join(LIB_ROOT, 'packages');
+
+// 项目模块特征(反向依赖项目的明显信号)
+const PROJECT_HINTS = [
+  /(^|\/)config\//, /(^|\/)core\//, /(^|\/)services\//, /(^|\/)systems\//,
+  /(^|\/)gameplay\//, /projectGameplayConfig/, /babylon-gltf-loader/,
+  /(^|\/)assets$/, /(^|\/)assets\/index/, /UIImages/, /configService/,
+];
+const ALLOWED_BARE = [/^@babylonjs\//, /^@fps\//, /^node:/];
+
+function walk(dir, out = []) {
+  if (!existsSync(dir)) return out;
+  for (const e of readdirSync(dir)) {
+    if (e === 'node_modules' || e === 'dist' || e.startsWith('.')) continue;
+    const p = join(dir, e);
+    const s = statSync(p);
+    if (s.isDirectory()) walk(p, out);
+    else if (/\.(ts|tsx|js|mjs)$/.test(e)) out.push(p);
+  }
+  return out;
+}
+
+function specifiers(src) {
+  const out = new Set();
+  let m;
+  // a) `... from '...'`(普通/重导出)
+  const fromRe = /\bfrom\s*['"]([^'"]+)['"]/g;
+  while ((m = fromRe.exec(src))) out.add(m[1]);
+  // b) 副作用导入 `import '...'`(无 from)
+  const sideRe = /\bimport\s+['"]([^'"]+)['"]/g;
+  while ((m = sideRe.exec(src))) out.add(m[1]);
+  // c) 动态 import('...')
+  const dynRe = /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;
+  while ((m = dynRe.exec(src))) out.add(m[1]);
+  return [...out];
+}
+
+function resolvesInLib(fromFile, spec) {
+  // 去掉 ?url / ?raw 等 query
+  const clean = spec.replace(/\?.*$/, '');
+  const base = resolve(dirname(fromFile), clean);
+  if (!base.startsWith(LIB_ROOT)) return { ok: false, reason: '逃出库根' };
+  const cands = [base, base + '.ts', base + '.tsx', base + '.js', base + '.mjs', base + '.json',
+    join(base, 'index.ts'), join(base, 'index.js')];
+  if (cands.some(existsSync)) return { ok: true };
+  return { ok: false, reason: '指向库内不存在的文件(可能本应指向项目)' };
+}
+
+const violations = [];
+// 扫:packages/ 根的运行时 .ts(非递归)+ packages/effects/ 全树
+const rootTsFiles = existsSync(PKG_ROOT)
+  ? readdirSync(PKG_ROOT).filter((e) => /\.(ts|tsx|js|mjs)$/.test(e)).map((e) => join(PKG_ROOT, e))
+  : [];
+const files = [...rootTsFiles, ...walk(join(PKG_ROOT, 'effects'))];
+for (const f of files) {
+  const src = readFileSync(f, 'utf8');
+  for (const spec of specifiers(src)) {
+    const rel = relative(LIB_ROOT, f);
+    if (spec.startsWith('.')) {
+      const r = resolvesInLib(f, spec);
+      if (!r.ok) violations.push({ file: rel, spec, reason: r.reason });
+    } else if (ALLOWED_BARE.some((re) => re.test(spec))) {
+      continue;
+    } else if (PROJECT_HINTS.some((re) => re.test(spec))) {
+      violations.push({ file: rel, spec, reason: '命中项目模块特征' });
+    }
+    // 其它裸包(第三方)默认放行
+  }
+}
+
+if (violations.length === 0) {
+  console.log('✅ 库纯净契约:无越界 import。');
+  process.exit(0);
+}
+console.log(`❌ 库纯净契约:发现 ${violations.length} 处越界/反向依赖 import:\n`);
+const byFile = {};
+for (const v of violations) (byFile[v.file] ??= []).push(v);
+for (const [file, vs] of Object.entries(byFile)) {
+  console.log(`  ${file}`);
+  for (const v of vs) console.log(`    → "${v.spec}"  [${v.reason}]`);
+}
+process.exit(1);

package/tooling/validate-effects.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+// 新增特效 guardrail · Layer 1(源码静态 lint,见 issue #3)。
+// 对每个 packages/effects/<id>/ 静态扫描,在「进库前 / 发版前」拦住会坑消费方的模式:
+//   1. 引用策略 —— 禁全量 glTF barrel / meshopt / draco / ktx2 等会被急切拉进 consumer 包的重运行时
+//      扩展(根治 v0.1.1 的 meshopt 事故);要核心 loader `@babylonjs/loaders/glTF/2.0/glTFLoader`。
+//   2. 资源内联 —— 资源用 `?url` 导入(库 build 才会内联成 base64);禁 `new URL(...,import.meta.url)`;
+//      引用的 .glb/.png/.js 资源必须存在。
+//   3. 契约 —— index.ts 导出合法 VfxEffectPackage(create+id+nameZh+defaultParams+debugParams,或 data 工厂)。
+//   4. 结构 —— 有 index.ts、vfx-params.json 合法 JSON;目录名 vs 导出 id(软提示)。
+//
+// 用法:
+//   node tooling/validate-effects.mjs                 # 扫全部特效
+//   node tooling/validate-effects.mjs --effect <id>   # 只扫一个(发版 gate / 回归用)
+//   node tooling/validate-effects.mjs --effects-dir <path>   # 换扫描根(回归 fixture 用)
+// 退出码:有 error → 1;只有 warning 或全过 → 0。
+import { readdirSync, statSync, readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LIB_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2);
+function flag(name) {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+const onlyEffect = flag('--effect');
+const effectsDir = resolve(flag('--effects-dir') ?? join(LIB_ROOT, 'packages', 'effects'));
+
+// ── 引用策略 ──────────────────────────────────────────────────────────────────
+// 唯一允许的 glTF loader 入口(只注册 2.0 核心,不引扩展)。
+const ALLOWED_LOADER_SPECIFIERS = new Set(['@babylonjs/loaders/glTF/2.0/glTFLoader']);
+// 轻量扩展白名单(按需扩;默认空 → 任何 @babylonjs/loaders 扩展都需显式审查后加入)。
+const ALLOWED_LOADER_EXTENSION_PREFIXES = [];
+// 明确点名的重 barrel/扩展(命中给定向修复提示)。
+const HEAVY_LOADER_HINTS = [
+  { re: /^@babylonjs\/loaders$/, why: '全量 loaders barrel(注册所有格式 + 全部 glTF 扩展)' },
+  { re: /^@babylonjs\/loaders\/glTF$/, why: '全量 glTF barrel(急切注册 EXT_meshopt_compression / KHR_draco 等扩展)' },
+  { re: /^@babylonjs\/loaders\/glTF\/2\.0$/, why: 'glTF 2.0 barrel(index,会拉入扩展注册)' },
+  { re: /EXT_meshopt_compression/, why: 'meshopt 扩展(把 MeshoptDecoder 拉进 consumer 包)' },
+  { re: /KHR_draco_mesh_compression/, why: 'draco 扩展(把 Draco 解码器拉进 consumer 包)' },
+  { re: /KHR_texture_basisu/, why: 'ktx2/basisu 扩展(把 basis transcoder 拉进 consumer 包)' },
+];
+const LOADER_FIX = '改用核心加载器 `import \'@babylonjs/loaders/glTF/2.0/glTFLoader\'`(只注册 2.0 核心,不引扩展);GLB 须为 plain(零扩展)。';
+
+// 在已剥注释的源码里直接出现 = 危险解码器引用(即便不是通过 loaders barrel 引入,如直接 import @babylonjs/core 的解码器)。
+const FORBIDDEN_RUNTIME_TOKENS = [
+  'EXT_meshopt_compression', 'MeshoptDecoder', 'meshopt_decoder',
+  'KHR_draco_mesh_compression', 'DracoCompression', 'DracoDecoder',
+  'KHR_texture_basisu', 'KhronosTextureContainer2', '_KTX2Decoder', 'MSCTranscoder', 'basis_transcoder',
+  'application/x-glb-brotli', 'brotli-dec-wasm',
+];
+
+// ── 工具 ──────────────────────────────────────────────────────────────────────
+function stripComments(src) {
+  // 先去块注释,再去行注释(用 (?<!:) 避免吃掉 URL 里的 `://`)。
+  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(?<!:)\/\/[^\n]*/g, '');
+}
+
+// import/require specifier(含无空格副作用导入、反引号动态 import、require)。
+function specifiers(src) {
+  const out = new Set();
+  let m;
+  const fromRe = /\bfrom\s*[`'"]([^`'"]+)[`'"]/g;
+  while ((m = fromRe.exec(src))) out.add(m[1]);
+  const sideRe = /\bimport\s*[`'"]([^`'"]+)[`'"]/g;        // \s* :允许 import'x'(零空格)
+  while ((m = sideRe.exec(src))) out.add(m[1]);
+  const dynRe = /\bimport\(\s*[`'"]([^`'"]+)[`'"]\s*\)/g;  // [`'"] :含模板字符串动态 import
+  while ((m = dynRe.exec(src))) out.add(m[1]);
+  const reqRe = /\brequire\(\s*[`'"]([^`'"]+)[`'"]\s*\)/g;
+  while ((m = reqRe.exec(src))) out.add(m[1]);
+  return [...out];
+}
+
+// 所有字符串字面量(单/双引号 + 不含插值的反引号)。用于在任意位置(import / require /
+// 字符串拼接 fragment)抓 heavy loader specifier —— 比只看 import 位置更难绕过。
+function stringLiterals(src) {
+  const out = [];
+  let m;
+  const re = /(['"])((?:[^'"\\]|\\.)*)\1|`([^`$\\]*)`/g;
+  while ((m = re.exec(src))) out.push(m[2] ?? m[3] ?? '');
+  return out;
+}
+
+// ── key 一致性(面板↔参数)用的轻量括号配平解析 ────────────────────────────────
+// 从 startIdx(open 字符 { 或 [ 处)取平衡子串(处理字符串/转义)。
+function balancedFrom(src, startIdx) {
+  const open = src[startIdx];
+  const close = open === '{' ? '}' : open === '[' ? ']' : null;
+  if (!close) return '';
+  let depth = 0, inStr = null;
+  for (let i = startIdx; i < src.length; i++) {
+    const c = src[i];
+    if (inStr) { if (c === '\\') { i++; continue; } if (c === inStr) inStr = null; continue; }
+    if (c === '"' || c === "'" || c === '`') { inStr = c; continue; }
+    if (c === open) depth++;
+    else if (c === close) { depth--; if (depth === 0) return src.slice(startIdx, i + 1); }
+  }
+  return '';
+}
+// 对象字面量(含外层 {})的顶层键名集合。
+function topLevelKeys(objStr) {
+  const keys = new Set();
+  let depth = 0, inStr = null, atProp = false;
+  for (let i = 0; i < objStr.length; i++) {
+    const c = objStr[i];
+    if (inStr) { if (c === '\\') { i++; continue; } if (c === inStr) inStr = null; continue; }
+    if (c === '"' || c === "'" || c === '`') {
+      if (depth === 1 && atProp) { const m = objStr.slice(i).match(/^(['"])([A-Za-z_$][\w$]*)\1\s*:/); if (m) { keys.add(m[2]); atProp = false; } }
+      inStr = c; continue;
+    }
+    if (c === '{' || c === '[' || c === '(') { depth++; if (depth === 1) atProp = true; continue; }
+    if (c === '}' || c === ']' || c === ')') { depth--; continue; }
+    if (depth === 1) {
+      if (c === ',') { atProp = true; continue; }
+      if (atProp && /[A-Za-z_$]/.test(c)) { const m = objStr.slice(i).match(/^([A-Za-z_$][\w$]*)\s*:/); if (m) { keys.add(m[1]); atProp = false; } }
+    }
+  }
+  return keys;
+}
+function valueAfterProp(code, prop) {
+  const m = new RegExp(`\\b${prop}\\s*:\\s*`).exec(code);
+  if (!m) return null;
+  let i = m.index + m[0].length;
+  while (i < code.length && /\s/.test(code[i])) i++;
+  return { idx: i, ch: code[i] };
+}
+// defaultParams 的键:支持内联 { } 或指向 const FOO = { }
+function defaultParamKeys(code) {
+  const v = valueAfterProp(code, 'defaultParams');
+  if (!v) return null;
+  if (v.ch === '{') return topLevelKeys(balancedFrom(code, v.idx));
+  const idm = code.slice(v.idx).match(/^([A-Za-z_$][\w$]*)/);
+  if (!idm) return null;
+  const cm = new RegExp(`\\b(?:const|let|var)\\s+${idm[1]}\\b[^=]*=\\s*`).exec(code);
+  if (!cm) return null;
+  let j = cm.index + cm[0].length;
+  while (j < code.length && /\s/.test(code[j])) j++;
+  if (code[j] !== '{') return null;
+  return topLevelKeys(balancedFrom(code, j));
+}
+// debugParams 数组里每个条目的 key
+function debugParamKeys(code) {
+  const v = valueAfterProp(code, 'debugParams');
+  if (!v || v.ch !== '[') return null;
+  const arr = balancedFrom(code, v.idx);
+  return new Set([...arr.matchAll(/\bkey\s*:\s*['"]([^'"]+)['"]/g)].map((m) => m[1]));
+}
+
+// 扫特效目录下"会被打包成模块"的代码文件;assets/ 是 ?url 运行时资产(非静态 import),排除。
+const CODE_EXT = /\.(tsx?|mts|cts|jsx?|mjs|cjs)$/;
+function codeFilesIn(dir, isRoot = true) {
+  const out = [];
+  for (const e of readdirSync(dir)) {
+    if (e === 'node_modules' || e.startsWith('.')) continue;
+    if (e === 'assets') continue; // ?url 资产目录,运行时按 URL 加载,不参与模块打包
+    const p = join(dir, e);
+    const s = statSync(p);
+    if (s.isDirectory()) out.push(...codeFilesIn(p, false));
+    else if (CODE_EXT.test(e)) out.push(p);
+  }
+  return out;
+}
+
+// ── 单特效校验 ────────────────────────────────────────────────────────────────
+function validateEffect(id) {
+  const dir = join(effectsDir, id);
+  const errors = [];
+  const warnings = [];
+  const indexPath = join(dir, 'index.ts');
+
+  if (!existsSync(indexPath)) {
+    errors.push(`缺少 index.ts(每个特效目录必须有 index.ts 导出 VfxEffectPackage)。`);
+    return { id, errors, warnings };
+  }
+
+  const files = codeFilesIn(dir);
+  const indexSrcRaw = readFileSync(indexPath, 'utf8');
+  const indexCode = stripComments(indexSrcRaw);
+
+  for (const file of files) {
+    const rel = relative(dirname(effectsDir), file);
+    const raw = readFileSync(file, 'utf8');
+    const code = stripComments(raw);
+
+    // 1) 引用策略:扫所有字符串字面量(覆盖 import / require / 字符串拼接 fragment / 反引号)。
+    //    凡以 @babylonjs/loaders 开头、又不是唯一允许的核心 loader / 白名单扩展 → 拦。
+    for (const lit of stringLiterals(code)) {
+      if (!lit.startsWith('@babylonjs/loaders')) continue;
+      if (ALLOWED_LOADER_SPECIFIERS.has(lit)) continue;
+      if (ALLOWED_LOADER_EXTENSION_PREFIXES.some((p) => lit.startsWith(p))) continue;
+      const hint = HEAVY_LOADER_HINTS.find((h) => h.re.test(lit));
+      errors.push(`[引用策略] ${rel} 引用 "${lit}"${hint ? `(${hint.why})` : '(非白名单 loaders 子路径)'} → ${LOADER_FIX}`);
+    }
+
+    // 1b) 危险解码器 token(剥注释后,覆盖 helper .js/.mjs 等)
+    for (const token of FORBIDDEN_RUNTIME_TOKENS) {
+      if (code.includes(token)) {
+        errors.push(`[引用策略] ${rel} 出现禁运行时标识 "${token}" → 会把重解码器拉进 consumer 包(违反 Playable bundle 策略,见 #2 v0.1.1)。`);
+      }
+    }
+
+    // 2) 资源:禁 new URL(...,import.meta.url)(含模板字符串/单双引号)
+    if (/new\s+URL\s*\(\s*[`'"][^`'"]+[`'"]\s*,\s*import\.meta\.url\s*\)/.test(code)) {
+      errors.push(`[资源] ${rel} 用了 \`new URL(..., import.meta.url)\` → 库 build 不会内联它。改用 \`import X from './path?url'\`(Phase1 已统一,见 #2)。`);
+    }
+
+    // 2b) ?url / ?raw 资源必须存在(query 里出现 url/raw 标志即算,容忍 ?url&inline 等附加 query)
+    for (const spec of specifiers(code)) {
+      if (!/[?&](url|raw)(?=&|=|$)/.test(spec)) continue;
+      if (!spec.startsWith('.')) continue; // 只校验相对资源
+      const cleaned = spec.replace(/\?.*$/, '');
+      const assetPath = resolve(dirname(file), cleaned);
+      if (!existsSync(assetPath)) {
+        errors.push(`[资源] ${rel} 引用的资源不存在:"${spec}"(解析为 ${relative(dirname(effectsDir), assetPath)})。`);
+      }
+    }
+  }
+
+  // 3) 契约:导出合法 VfxEffectPackage
+  // data 类用 createManifestRuntimeEffectPackage / createDataDrivenEffectPackage;
+  // 另有共享工厂(如 createWoodSawdustEffectPackage)。统一识别 create*EffectPackage( 调用。
+  const usesFactory = /\bcreate\w*EffectPackage\s*\(/.test(indexCode);
+  // create 可为方法 create( / 泛型 create<T>( / 箭头属性 create: (ctx)=>
+  const hasInlineShape = /\bcreate\s*[(:<]/.test(indexCode)
+    && /\bid\s*:/.test(indexCode)
+    && /\bnameZh\s*:/.test(indexCode)
+    && /\bdefaultParams\b/.test(indexCode)
+    && /\bdebugParams\b/.test(indexCode);
+  // index.ts 仅做 re-export(package 定义在 ./impl 等同目录模块)也算合规
+  const reExportsRelative = /export\s+(?:\*|\{[^}]*\}|.+\s+as\s+default)\s+from\s*[`'"]\.[^`'"]*[`'"]/.test(indexCode);
+  const hasExport = /\bexport\b/.test(indexCode);
+  if (!hasExport) {
+    errors.push(`[契约] index.ts 没有任何 export(需导出 VfxEffectPackage)。`);
+  } else if (!usesFactory && !hasInlineShape && !reExportsRelative) {
+    errors.push(`[契约] index.ts 未检测到合法 VfxEffectPackage:code 类需 create+id+nameZh+defaultParams+debugParams;data 类用 create*EffectPackage 工厂;或 re-export 自同目录模块。`);
+  }
+
+  // 3b) 面板↔参数 key 一致性:每个 debugParams[].key 必须在 defaultParams 里有默认值,
+  //     否则面板生成的旋钮调它不生效(以 undefined 起步)。仅对 inline code 特效;
+  //     工厂/data 类的 default/debug 由工厂生成,跳过(解析不到也跳过,不误报)。
+  if (hasInlineShape && !usesFactory && !reExportsRelative) {
+    const defaultKeys = defaultParamKeys(indexCode);
+    const debugKeys = debugParamKeys(indexCode);
+    if (defaultKeys && debugKeys) {
+      const orphan = [...debugKeys].filter((k) => !defaultKeys.has(k));
+      if (orphan.length) {
+        errors.push(`[参数] debugParams 旋钮 [${orphan.join(', ')}] 在 defaultParams 里没有对应默认值 → 面板调它不生效(以 undefined 起步)。把这些 key 补进 defaultParams,或修正 debugParams 的 key 使其与 defaultParams/create() 读取的 key 一致。`);
+      }
+    }
+  }
+
+  // 4) 结构:vfx-params.json
+  const paramsPath = join(dir, 'vfx-params.json');
+  if (existsSync(paramsPath)) {
+    try {
+      JSON.parse(readFileSync(paramsPath, 'utf8'));
+    } catch (e) {
+      errors.push(`[结构] vfx-params.json 不是合法 JSON:${e.message}`);
+    }
+  } else {
+    warnings.push(`[结构] 缺 vfx-params.json(项目调参种子;建议补一个 {schemaVersion,effectId,params:{}})。`);
+  }
+  // 注:本库导出 id 可带命名空间(如 run-footstep-dust → build.particle.run_footstep_dust),
+  // 故不强制「目录名==导出 id」;tooling(generate-index/vfx-cli)统一以目录名作 dir key。
+
+  return { id, errors, warnings };
+}
+
+// ── 主流程 ────────────────────────────────────────────────────────────────────
+if (!existsSync(effectsDir)) {
+  console.error(`✗ effects 目录不存在:${effectsDir}`);
+  process.exit(1);
+}
+const ids = (onlyEffect ? [onlyEffect] : readdirSync(effectsDir))
+  .filter((id) => {
+    try { return statSync(join(effectsDir, id)).isDirectory(); } catch { return false; }
+  })
+  .sort();
+
+let errorCount = 0;
+let warnCount = 0;
+const failed = [];
+for (const id of ids) {
+  const { errors, warnings } = validateEffect(id);
+  errorCount += errors.length;
+  warnCount += warnings.length;
+  if (errors.length || warnings.length) {
+    const mark = errors.length ? '✗' : '⚠';
+    console.log(`${mark} ${id}`);
+    for (const e of errors) console.log(`    ✗ ${e}`);
+    for (const w of warnings) console.log(`    ⚠ ${w}`);
+  }
+  if (errors.length) failed.push(id);
+}
+
+console.log('');
+if (errorCount === 0) {
+  console.log(`✅ Layer 1 特效 lint 通过:${ids.length} 个特效,0 error${warnCount ? `,${warnCount} warning(不阻断)` : ''}。`);
+  process.exit(0);
+}
+console.log(`❌ Layer 1 特效 lint:${failed.length}/${ids.length} 个特效有问题,共 ${errorCount} error。`);
+process.exit(1);

package/tooling/validate.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// `pnpm validate` 聚合闸(issue #3 串联):一条命令跑完所有 guardrail。
+//   boundary(纯净契约) → effects(Layer 1 源码 lint) → typecheck → build → check-dist(Layer 2)
+// 任一步失败即中止并以非 0 退出(作者本地 / CI PR / 发版 gate 共用,见 release.mjs)。
+//
+// 用法:
+//   node tooling/validate.mjs            # 全量(含 build + dist 扫描)
+//   node tooling/validate.mjs --no-build # 快速:只 boundary + effects + typecheck(跳过 build/dist)
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const LIB_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const noBuild = process.argv.includes('--no-build');
+
+function bin(name) {
+  const local = join(LIB_ROOT, 'node_modules', '.bin', name);
+  return existsSync(local) ? local : name; // 退回 PATH(如 CI 已全局装)
+}
+
+const steps = [
+  { name: '纯净契约 (validate-boundary)', cmd: 'node', args: ['tooling/validate-boundary.mjs'] },
+  { name: 'Layer 1 特效 lint (validate-effects)', cmd: 'node', args: ['tooling/validate-effects.mjs'] },
+  { name: 'typecheck (tsc --noEmit)', cmd: bin('tsc'), args: ['-p', 'tsconfig.json', '--noEmit'] },
+];
+if (!noBuild) {
+  steps.push({ name: 'build (vite)', cmd: bin('vite'), args: ['build'] });
+  steps.push({ name: 'Layer 2 dist 禁运行时 (check-dist-runtime)', cmd: 'node', args: ['tooling/check-dist-runtime.mjs'] });
+}
+
+console.log(`▶ pnpm validate${noBuild ? ' --no-build' : ''} —— ${steps.length} 步\n`);
+const results = [];
+for (const [i, step] of steps.entries()) {
+  console.log(`── [${i + 1}/${steps.length}] ${step.name} ──────────────────────────`);
+  const r = spawnSync(step.cmd, step.args, { cwd: LIB_ROOT, stdio: 'inherit' });
+  const ok = r.status === 0;
+  results.push({ name: step.name, ok });
+  console.log('');
+  if (!ok) {
+    console.log('❌ validate 中止于:' + step.name + (r.error ? `(${r.error.message})` : ` (exit ${r.status})`));
+    summarize(results, i + 1, steps.length);
+    process.exit(1);
+  }
+}
+console.log('✅ validate 全部通过。');
+summarize(results, steps.length, steps.length);
+
+function summarize(results, ran, total) {
+  console.log('\n摘要:');
+  for (const r of results) console.log(`  ${r.ok ? '✅' : '❌'} ${r.name}`);
+  if (ran < total) console.log(`  ⋯ 剩余 ${total - ran} 步未执行(已中止)。`);
+}