@fps-games/vfx 0.3.2 → 0.3.4

package/tooling/test-guardrails.mjs

@@ -1,157 +0,0 @@
-#!/usr/bin/env node
-// guardrail 回归用例(issue #3 验收最后一条):
-//   "故意造一个引全量 glTF 的特效 → 被 Layer 1 + Layer 2 双重拦下"。
-// 全程 hermetic(写临时目录,不碰 packages/effects 与真实 dist),跑完即清理。
-//   Layer 1:对一批坏 fixture 跑 validate-effects,断言每个都被拒(exit≠0)+ 对干净 fixture 断言放行。
-//   Layer 2:造一个含 meshopt token 的假 dist chunk(= 全量 glTF loader 会拉进来的东西),
-//            断言 check-dist-runtime 命中并归因到引它的特效;且 `basis` 变量名不被误报。
-// 用法:node tooling/test-guardrails.mjs   退出码:全过 0,任一断言失败 1。
-import { spawnSync } from 'node:child_process';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { resolve, dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const LIB_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const tmp = mkdtempSync(join(tmpdir(), 'vfx-guardrail-'));
-let failures = 0;
-
-function runValidateEffects(effectsDir) {
-  return spawnSync('node', ['tooling/validate-effects.mjs', '--effects-dir', effectsDir], { cwd: LIB_ROOT, encoding: 'utf8' });
-}
-function runCheckDist(distDir) {
-  return spawnSync('node', ['tooling/check-dist-runtime.mjs', '--dist', distDir], { cwd: LIB_ROOT, encoding: 'utf8' });
-}
-function assert(cond, msg, detail = '') {
-  if (cond) { console.log(`  ✅ ${msg}`); }
-  else { console.log(`  ❌ ${msg}${detail ? `\n     ${detail.replace(/\n/g, '\n     ')}` : ''}`); failures += 1; }
-}
-function write(p, content) { mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, content); }
-
-try {
-  // ── Layer 1 ────────────────────────────────────────────────────────────────
-  console.log('Layer 1（validate-effects）回归:');
-  const fxRoot = join(tmp, 'effects');
-
-  // 坏 1:引全量 glTF barrel(meshopt 事故的根因)
-  write(join(fxRoot, 'full-gltf', 'index.ts'),
-    `import '@babylonjs/loaders/glTF';\nexport const e = { id:'full-gltf', nameZh:'x', defaultParams:{}, debugParams:[], create(){ return { root:{}, dispose(){} }; } };\n`);
-  // 坏 2:new URL 资源 + 缺资源
-  write(join(fxRoot, 'new-url', 'index.ts'),
-    `const u = new URL('./assets/a.bin', import.meta.url);\nimport tex from './assets/missing.png?url';\nexport const e = { id:'new-url', nameZh:'x', defaultParams:{}, debugParams:[], create(){ return { root:{}, dispose(){} }; } };\n`);
-  // 坏 3:直接引解码器类(间接 token)
-  write(join(fxRoot, 'decoder-token', 'index.ts'),
-    `import { MeshoptDecoder } from '@babylonjs/core/Meshes/Compression/meshoptCompression';\nexport const e = { id:'decoder-token', nameZh:'x', defaultParams:{}, debugParams:[], create(){ MeshoptDecoder.UseInstances = true; return { root:{}, dispose(){} }; } };\n`);
-  // 坏 4:不是合法 package
-  write(join(fxRoot, 'not-a-package', 'index.ts'), `export const notAPackage = { hello: 'world' };\n`);
-  // 干净:核心 loader + ?url 存在 + 合法契约 + 注释里提 meshopt 不应误报
-  write(join(fxRoot, 'clean', 'assets', 'm.glb'), 'GLB');
-  write(join(fxRoot, 'clean', 'index.ts'),
-    `// 用核心 loader,避免 EXT_meshopt_compression / MeshoptDecoder 被拉进包\nimport '@babylonjs/loaders/glTF/2.0/glTFLoader';\nimport url from './assets/m.glb?url';\nexport const e = { id:'clean', nameZh:'干净', defaultParams:{ a:1 }, debugParams:[{key:'a',label:'a',kind:'number'}], create(){ return { root:{}, dispose(){} }; } };\n`);
-  write(join(fxRoot, 'clean', 'vfx-params.json'), `{ "schemaVersion":"vfx-params/1.0","effectId":"clean","params":{} }`);
-
-  // 一次扫整根:坏的应被拒
-  const allRes = runValidateEffects(fxRoot);
-  assert(allRes.status !== 0, '坏 fixture 集合被 Layer 1 拒绝(exit≠0)', allRes.stdout);
-  for (const [bad, needle] of [
-    ['full-gltf', '@babylonjs/loaders/glTF'],
-    ['new-url', 'new URL'],
-    ['decoder-token', 'MeshoptDecoder'],
-    ['not-a-package', '未检测到合法 VfxEffectPackage'],
-  ]) {
-    assert(allRes.stdout.includes(bad) && allRes.stdout.includes(needle), `命中坏 fixture「${bad}」并给出原因`, allRes.stdout);
-  }
-  // 规避向量回归(对抗式审查发现并已堵住的绕过手法,每个都必须仍被拦):
-  const evasion = join(tmp, 'evasion');
-  // 把全量 barrel + MeshoptDecoder 藏在 helper .js 里(非 .ts sibling)
-  write(join(evasion, 'sibling-js', 'index.ts'), `import './heavy.js';\nexport const e={id:'x',nameZh:'x',defaultParams:{},debugParams:[],create(){return{root:{},dispose(){}};}};\n`);
-  write(join(evasion, 'sibling-js', 'heavy.js'), `import '@babylonjs/loaders/glTF';\nexport const z = MeshoptDecoder;\n`);
-  // 无空格副作用导入
-  write(join(evasion, 'nospace', 'index.ts'), `import'@babylonjs/loaders/glTF';\nexport const e={id:'x',nameZh:'x',defaultParams:{},debugParams:[],create(){return{root:{},dispose(){}};}};\n`);
-  // 模板字符串动态 import
-  write(join(evasion, 'tmpl-dyn', 'index.ts'), "export const e={id:'x',nameZh:'x',defaultParams:{},debugParams:[],async create(){await import(`@babylonjs/loaders/glTF`);return{root:{},dispose(){}};}};\n");
-  // 字符串拼接动态 import
-  write(join(evasion, 'concat', 'index.ts'), `export const e={id:'x',nameZh:'x',defaultParams:{},debugParams:[],async create(){await import('@babylonjs/loaders'+'/glTF');return{root:{},dispose(){}};}};\n`);
-  // 模板字符串 new URL
-  write(join(evasion, 'tmpl-url', 'index.ts'), "const u=new URL(`./a.glb`,import.meta.url);\nexport const e={id:'x',nameZh:'x',defaultParams:{},debugParams:[],create(){return{root:{},dispose(){}};}};\n");
-  const evRes = runValidateEffects(evasion);
-  assert(evRes.status !== 0, '规避向量集合被 Layer 1 拒绝(exit≠0)', evRes.stdout);
-  for (const id of ['sibling-js', 'nospace', 'tmpl-dyn', 'concat', 'tmpl-url']) {
-    assert(evRes.stdout.includes(id), `规避向量「${id}」被拦下`, evRes.stdout);
-  }
-
-  // 契约误报回归:箭头 create / 泛型 create / re-export barrel 都应放行(0 error)
-  const contractOk = join(tmp, 'contract-ok');
-  write(join(contractOk, 'arrow', 'index.ts'), `export const e={id:'x',nameZh:'测',defaultParams:{a:1},debugParams:[{key:'a',label:'a',kind:'number'}],create:(ctx)=>({root:ctx.root,dispose(){}})};\n`);
-  write(join(contractOk, 'arrow', 'vfx-params.json'), `{"schemaVersion":"vfx-params/1.0","effectId":"arrow","params":{}}`);
-  write(join(contractOk, 'barrel', 'index.ts'), `export * from './impl';\n`);
-  write(join(contractOk, 'barrel', 'impl.ts'), `export const e={id:'x',nameZh:'测',defaultParams:{},debugParams:[],create(){return{root:{},dispose(){}};}};\n`);
-  write(join(contractOk, 'barrel', 'vfx-params.json'), `{"schemaVersion":"vfx-params/1.0","effectId":"barrel","params":{}}`);
-  const contractRes = runValidateEffects(contractOk);
-  assert(contractRes.status === 0, '箭头 create / re-export barrel 合法写法被放行(无契约误报)', contractRes.stdout);
-
-  // 面板↔参数 key 一致性:debugParams 旋钮的 key 不在 defaultParams → 拦;对齐 → 放行
-  const keyBad = join(tmp, 'key-bad');
-  write(join(keyBad, 'orphan-knob', 'index.ts'),
-    `const DEFAULT_PARAMS = { lifetime: 1, scale: 2 };\nexport const e = { id:'orphan-knob', nameZh:'测', defaultParams: DEFAULT_PARAMS, debugParams: [ {key:'lifetime',label:'a',kind:'lifetime'}, {key:'scale',label:'b',kind:'scale'}, {key:'partcileCount',label:'拼错',kind:'number'} ], create(){ return { root:{}, dispose(){} }; } };\n`);
-  write(join(keyBad, 'orphan-knob', 'vfx-params.json'), `{"schemaVersion":"vfx-params/1.0","effectId":"orphan-knob","params":{}}`);
-  const keyBadRes = runValidateEffects(keyBad);
-  assert(keyBadRes.status !== 0 && /partcileCount/.test(keyBadRes.stdout), 'debugParams 旋钮 key 无对应 defaultParams 被拦(面板↔参数一致性)', keyBadRes.stdout);
-
-  const keyOk = join(tmp, 'key-ok');
-  write(join(keyOk, 'aligned', 'index.ts'),
-    `const DEFAULT_PARAMS = { lifetime: 1, count: 8 };\nexport const e = { id:'aligned', nameZh:'测', defaultParams: DEFAULT_PARAMS, debugParams: [ {key:'lifetime',label:'a',kind:'lifetime'}, {key:'count',label:'b',kind:'number'} ], create(){ return { root:{}, dispose(){} }; } };\n`);
-  write(join(keyOk, 'aligned', 'vfx-params.json'), `{"schemaVersion":"vfx-params/1.0","effectId":"aligned","params":{}}`);
-  const keyOkRes = runValidateEffects(keyOk);
-  assert(keyOkRes.status === 0, 'debugParams.key ⊆ defaultParams.key 时放行', keyOkRes.stdout);
-
-  // 干净 fixture 单独扫应放行
-  const cleanRoot = join(tmp, 'effects-clean');
-  write(join(cleanRoot, 'clean', 'assets', 'm.glb'), 'GLB');
-  write(join(cleanRoot, 'clean', 'index.ts'),
-    `// 注释提到 EXT_meshopt_compression / MeshoptDecoder 不应误报\nimport '@babylonjs/loaders/glTF/2.0/glTFLoader';\nimport url from './assets/m.glb?url';\nexport const e = { id:'clean', nameZh:'干净', defaultParams:{ a:1 }, debugParams:[{key:'a',label:'a',kind:'number'}], create(){ return { root:{}, dispose(){} }; } };\n`);
-  write(join(cleanRoot, 'clean', 'vfx-params.json'), `{ "schemaVersion":"vfx-params/1.0","effectId":"clean","params":{} }`);
-  const cleanRes = runValidateEffects(cleanRoot);
-  assert(cleanRes.status === 0, '干净 fixture 被放行(注释里的 meshopt 字样不误报)', cleanRes.stdout);
-
-  // ── Layer 2 ────────────────────────────────────────────────────────────────
-  console.log('\nLayer 2（check-dist-runtime）回归:');
-  const fakeDist = join(tmp, 'dist');
-  // 共享 heavy chunk = 全量 glTF loader 会拉进来的 meshopt 运行时
-  write(join(fakeDist, 'chunks', 'heavy-aaa.js'),
-    `export const EXT = "EXT_meshopt_compression";\nexport function setup(){ MeshoptDecoder.UseInstances = true; }\n`);
-  // light chunk:含 `basis` 变量名(必须不被误报)
-  write(join(fakeDist, 'chunks', 'light-bbb.js'), `export const ringBasis = "a normal basis variable";\n`);
-  write(join(fakeDist, 'index.js'), `import { ringBasis } from "./chunks/light-bbb.js";\nconsole.log(ringBasis);\n`);
-  write(join(fakeDist, 'effects', 'bad-effect', 'index.js'), `import { setup } from "../../chunks/heavy-aaa.js";\nsetup();\n`);
-  write(join(fakeDist, 'effects', 'clean-effect', 'index.js'), `import { ringBasis } from "../../chunks/light-bbb.js";\nconsole.log(ringBasis);\n`);
-  const distRes = runCheckDist(fakeDist);
-  assert(distRes.status !== 0, '含 meshopt 的假 dist 被 Layer 2 拦下(exit≠0)', distRes.stdout);
-  assert(distRes.stdout.includes('bad-effect') && /meshopt/i.test(distRes.stdout), '命中并归因到引入它的特效「bad-effect」', distRes.stdout);
-  assert(!distRes.stdout.includes('clean-effect'), '只引 light chunk 的「clean-effect」不被误报', distRes.stdout);
-  assert(!/✗.*basis['"]?\s*$/m.test(distRes.stdout) && !distRes.stdout.includes('light-bbb'), '`basis` 变量名不触发误报', distRes.stdout);
-
-  // Layer 2 鲁棒性回归:meshopt 藏 .mjs chunk 仍被拦
-  const distMjs = join(tmp, 'dist-mjs');
-  write(join(distMjs, 'chunks', 'heavy.mjs'), `export const x="EXT_meshopt_compression"; MeshoptDecoder.foo();\n`);
-  write(join(distMjs, 'effects', 'evil', 'index.js'), `import '../../chunks/heavy.mjs';\n`);
-  const mjsRes = runCheckDist(distMjs);
-  assert(mjsRes.status !== 0 && mjsRes.stdout.includes('evil'), 'meshopt 藏 .mjs chunk 仍被 Layer 2 拦下并归因', mjsRes.stdout);
-
-  // Layer 2 假阳性回归:.wasm 错误消息(无 /)+ 注释里的 token 都不应误报
-  const distFp = join(tmp, 'dist-fp');
-  write(join(distFp, 'effects', 'a', 'index.js'), `export function c(){ throw new Error("dropped optional physics.wasm"); }\n`);
-  write(join(distFp, 'effects', 'b', 'index.js'), `/** intentionally avoids MeshoptDecoder and DracoCompression */\nexport const e=1;\n`);
-  const fpRes = runCheckDist(distFp);
-  assert(fpRes.status === 0, '.wasm 文件名错误消息 + 注释里的禁 token 不触发 Layer 2 误报', fpRes.stdout);
-} finally {
-  rmSync(tmp, { recursive: true, force: true });
-}
-
-console.log('');
-if (failures === 0) {
-  console.log('✅ guardrail 回归全部通过(全量 glTF 特效被 Layer 1 + Layer 2 双重拦下;无误报)。');
-  process.exit(0);
-}
-console.log(`❌ guardrail 回归:${failures} 条断言失败。`);
-process.exit(1);

package/tooling/validate-boundary.mjs

@@ -1,92 +0,0 @@
-#!/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

@@ -1,304 +0,0 @@
-#!/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

@@ -1,53 +0,0 @@
-#!/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} 步未执行(已中止)。`);
-}