@fps-games/vfx 0.1.1

package/packages/resource.particle.viscous_oil_suction/provenance/asset-map.json

@@ -0,0 +1,111 @@
+{
+  "schemaVersion": "vfx-asset-map/1.0",
+  "generatedAt": "2026-05-21T13:04:29.644Z",
+  "sourcePackage": "vfx-intermediate/cocos-babylon-packages/gas_town_oil_suction",
+  "policy": {
+    "runtimeAssetsRoot": "assets/",
+    "sourceAssetsRoot": "source/",
+    "note": "assets/ contains files loaded by Babylon runtime. source/cocos/assets/ preserves the original Cocos asset tree for traceability and reconversion."
+  },
+  "entries": [
+    {
+      "id": "glow_ad",
+      "kind": "texture",
+      "group": "textures",
+      "role": "babylon-runtime",
+      "runtimeUse": true,
+      "packagePath": "assets/textures/Glow ad.png",
+      "sourcePackagePath": "assets/textures/Glow ad.png",
+      "sourceArchivePath": "source/cocos/assets/ArtResources/Effect/GasTown_OilSuction/Glow ad.png",
+      "sourcePath": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction/source/cocos/assets/ArtResources/Effect/GasTown_OilSuction/Glow ad.png",
+      "sourceId": "dd44b0a9-0998-4c24-ba2e-d6ac9d1bebb7@6c48a",
+      "usedBy": [],
+      "originalProjectPath": "assets/ArtResources/Effect/GasTown_OilSuction/Glow ad.png"
+    },
+    {
+      "id": "asset",
+      "kind": "material",
+      "group": "materials",
+      "role": "source-evidence",
+      "runtimeUse": false,
+      "packagePath": "source/cocos/assets/ArtResources/Effect/GasTown_OilSuction/石油.mtl",
+      "sourcePackagePath": "assets/materials/石油.mtl",
+      "sourceArchivePath": "source/cocos/assets/ArtResources/Effect/GasTown_OilSuction/石油.mtl",
+      "sourcePath": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction/source/cocos/assets/ArtResources/Effect/GasTown_OilSuction/石油.mtl",
+      "sourceId": "4aabf2b0-1d20-4e13-9384-ae47eb8522aa",
+      "usedBy": [],
+      "originalProjectPath": "assets/ArtResources/Effect/GasTown_OilSuction/石油.mtl"
+    },
+    {
+      "id": "particle_emitter_oil_suction_v1",
+      "kind": "script",
+      "group": "scripts",
+      "role": "babylon-runtime",
+      "runtimeUse": true,
+      "packagePath": "assets/runtime/gas_town_oil_suction/particleEmitter.v1.js",
+      "sourcePackagePath": "assets/runtime/gas_town_oil_suction/particleEmitter.v1.js",
+      "sourceArchivePath": null,
+      "sourcePath": null,
+      "sourceId": null,
+      "usedBy": []
+    },
+    {
+      "id": "02-normalized-vfx",
+      "kind": "raw",
+      "group": "raw",
+      "role": "source-evidence",
+      "runtimeUse": false,
+      "packagePath": "source/02-normalized-vfx.json",
+      "sourcePackagePath": "source/02-normalized-vfx.json",
+      "sourceArchivePath": null,
+      "sourcePath": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction/source/02-normalized-vfx.json",
+      "sourceId": null,
+      "usedBy": []
+    },
+    {
+      "id": "01-source-dump",
+      "kind": "raw",
+      "group": "raw",
+      "role": "source-evidence",
+      "runtimeUse": false,
+      "packagePath": "source/01-source-dump.json",
+      "sourcePackagePath": "source/01-source-dump.json",
+      "sourceArchivePath": null,
+      "sourcePath": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction/source/01-source-dump.json",
+      "sourceId": null,
+      "usedBy": []
+    },
+    {
+      "id": "asset",
+      "kind": "raw",
+      "group": "raw",
+      "role": "source-evidence",
+      "runtimeUse": false,
+      "packagePath": "source/raw/吸石油.prefab",
+      "sourcePackagePath": "source/raw/吸石油.prefab",
+      "sourceArchivePath": "source/cocos/assets/ArtResources/Effect/GasTown_OilSuction/吸石油.prefab",
+      "sourcePath": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction/source/cocos/assets/ArtResources/Effect/GasTown_OilSuction/吸石油.prefab",
+      "sourceId": "29954e7e-d137-4c8b-a730-4f0320cbece8",
+      "usedBy": [],
+      "originalProjectPath": "assets/ArtResources/Effect/GasTown_OilSuction/吸石油.prefab"
+    },
+    {
+      "id": "asset.meta",
+      "kind": "raw",
+      "group": "raw",
+      "role": "source-evidence",
+      "runtimeUse": false,
+      "packagePath": "source/raw/吸石油.prefab.meta",
+      "sourcePackagePath": "source/raw/吸石油.prefab.meta",
+      "sourceArchivePath": "source/cocos/assets/ArtResources/Effect/GasTown_OilSuction/吸石油.prefab.meta",
+      "sourcePath": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction/source/cocos/assets/ArtResources/Effect/GasTown_OilSuction/吸石油.prefab.meta",
+      "sourceId": "29954e7e-d137-4c8b-a730-4f0320cbece8",
+      "usedBy": [],
+      "originalProjectPath": "assets/ArtResources/Effect/GasTown_OilSuction/吸石油.prefab.meta"
+    }
+  ],
+  "gcsPrefix": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction",
+  "sourceArchivePrefix": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction/source",
+  "fullProvenancePrefix": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction/provenance",
+  "canonicalSource": "gcs"
+}

package/packages/resource.particle.viscous_oil_suction/provenance/lineage.json

@@ -0,0 +1,45 @@
+{
+  "schemaVersion": "vfx-library-lineage/1.0",
+  "savedAt": "2026-05-21T13:04:29.665Z",
+  "sourcePackage": "vfx-intermediate/cocos-babylon-packages/gas_town_oil_suction",
+  "sourceEffect": "03-effect.json",
+  "libraryPackage": "packages/resource.particle.viscous_oil_suction",
+  "effectId": "resource.particle.viscous_oil_suction",
+  "media": {
+    "previewVideo": "media/preview.webm",
+    "previewWebm": "media/preview.webm",
+    "previewMp4": "media/preview.mp4",
+    "previewGif": "media/preview.gif",
+    "thumbnail": "media/thumbnail.png",
+    "gcsUri": null
+  },
+  "recording": {
+    "provider": "browser-mediarecorder",
+    "recordedAt": "2026-05-21T13:04:30.575Z",
+    "mimeType": "video/webm;codecs=vp9",
+    "durationSec": 10,
+    "fps": 30,
+    "media": {
+      "previewVideo": "media/preview.webm",
+      "previewWebm": "media/preview.webm",
+      "previewMp4": "media/preview.mp4",
+      "previewGif": "media/preview.gif",
+      "thumbnail": "media/thumbnail.png",
+      "gcsUri": null
+    }
+  },
+  "description": {
+    "provider": "litellm",
+    "status": "described",
+    "model": "gemini-3.1-pro-preview",
+    "generatedAt": "2026-05-21T13:30:34.263Z"
+  },
+  "gcsPrefix": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction",
+  "sourceArchivePrefix": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction/source",
+  "fullProvenancePrefix": "gs://fps-vfx-library/packages/resource.particle.viscous_oil_suction/provenance",
+  "previousIds": [
+    "world.particle.gas_town_oil_suction",
+    "world.particle.viscous_oil_suction"
+  ],
+  "renamedAt": "2026-05-21T13:39:08.485Z"
+}

package/packages/types.ts

@@ -0,0 +1,107 @@
+import type { Scene } from '@babylonjs/core/scene';
+import type { Vector3 } from '@babylonjs/core/Maths/math.vector';
+import type { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+
+export type VfxDebugAnchor = 'playerRight' | 'player';
+
+export type VfxParamValue = number | string | VfxColorValue;
+export type VfxParamValues = Record<string, VfxParamValue>;
+
+export interface VfxColorValue {
+  r: number;
+  g: number;
+  b: number;
+}
+
+export type VfxParamKind =
+  | 'number'
+  | 'color'
+  | 'enum'
+  | 'opacity'
+  | 'lifetime'
+  | 'scale';
+
+export interface VfxParamDefinitionBase {
+  key: string;
+  label: string;
+  kind: VfxParamKind;
+  description?: string;
+}
+
+export interface VfxNumberParamDefinition extends VfxParamDefinitionBase {
+  kind: 'number' | 'opacity' | 'lifetime' | 'scale';
+  min?: number;
+  max?: number;
+  step?: number;
+}
+
+export interface VfxColorParamDefinition extends VfxParamDefinitionBase {
+  kind: 'color';
+}
+
+export interface VfxEnumParamOption {
+  value: string;
+  label: string;
+}
+
+export interface VfxEnumParamDefinition extends VfxParamDefinitionBase {
+  kind: 'enum';
+  options: VfxEnumParamOption[];
+}
+
+export type VfxParamDefinition = VfxNumberParamDefinition | VfxColorParamDefinition | VfxEnumParamDefinition;
+
+export interface VfxEffectPackageContext<PParams extends VfxParamValues = VfxParamValues> {
+  scene: Scene;
+  root: TransformNode;
+  position: Vector3;
+  rotationY: number;
+  renderingGroupId?: number;
+  params: PParams;
+}
+
+export interface VfxEffectHandle {
+  root: TransformNode;
+  ready?: Promise<void>;
+  dispose(): void;
+}
+
+export interface VfxEffectManifest {
+  id: string;
+  nameZh: string;
+  assets?: string[];
+  source?: string;
+}
+
+export interface VfxSpawnParamKeys {
+  offsetX?: string;
+  offsetY?: string;
+  offsetZ?: string;
+}
+
+export interface VfxSpawnTransform {
+  position?: Vector3;
+  rotationY?: number;
+  renderingGroupId?: number;
+}
+
+export interface VfxParamsFile {
+  schemaVersion: string;
+  effectId?: string;
+  updatedAt?: string | null;
+  params?: Partial<VfxParamValues>;
+}
+
+export interface VfxEffectPackage<PParams extends VfxParamValues = VfxParamValues> {
+  id: string;
+  nameZh: string;
+  manifest?: VfxEffectManifest;
+  defaultParams: PParams;
+  debugAnchor?: VfxDebugAnchor;
+  spawnParams?: VfxSpawnParamKeys;
+  savedParams?: Partial<VfxParamValues>;
+  debugParams: VfxParamDefinition[];
+  create(context: VfxEffectPackageContext<PParams>): VfxEffectHandle;
+}
+
+export type VfxDebugOverrides = Record<string, Partial<VfxParamValues>>;

package/tooling/check-dist-runtime.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// 新增特效 guardrail · Layer 2(构建产物禁运行时扫描,见 issue #3,最强一层)。
+// `pnpm build` 之后扫 dist/,镜像消费方 Playable bundle 策略(lumber-order
+// scripts/check-playable-asset-bundle.mjs 的 forbiddenTokens),把"会坑消费方"的重运行时
+// 提前到库侧拦住 —— 即便它是被某个特效"间接"拉进来的(顺着 dist 的 chunk import 图归因到特效)。
+//
+// 用法:
+//   node tooling/check-dist-runtime.mjs              # 扫 dist/
+//   node tooling/check-dist-runtime.mjs --dist <dir> # 换扫描目录(回归 fixture 用)
+// 退出码:命中 → 1;干净 → 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)), '..');
+const argv = process.argv.slice(2);
+const distArg = argv.indexOf('--dist') >= 0 ? argv[argv.indexOf('--dist') + 1] : undefined;
+const DIST = resolve(distArg ?? join(LIB_ROOT, 'dist'));
+
+// 精确 token —— 类名/扩展名/MIME,绝不用宽松子串(如 `basis` 会误报 RingBasis 变量)。
+// 与 lumber-order check-playable-asset-bundle.mjs 的 forbiddenTokens 对齐 + 补 draco/ktx2。
+const SUBSTRING_TOKENS = [
+  'EXT_meshopt_compression', 'MeshoptDecoder', 'meshopt_decoder',
+  'KHR_draco_mesh_compression', 'DracoCompression', 'DracoDecoder', 'draco_decoder', 'draco_wasm_wrapper',
+  'KHR_texture_basisu', 'KhronosTextureContainer2', '_KTX2Decoder', 'MSCTranscoder', 'basis_transcoder',
+  'application/x-glb-brotli', 'brotli-dec-wasm',
+  'application/wasm', 'data:application/wasm',
+  'WebAssembly.Module', 'WebAssembly.instantiate',
+];
+// `.wasm` 资源 URL:要求路径分隔符(/),只拦真资源路径如 "./decoder.wasm"/"chunks/x.wasm",
+// 不误报纯文件名字符串(错误消息 "physics.wasm" / debug 标签 "ringBurst.wasm" 无 /)。
+const WASM_URL_RE = /['"][^'"]*\/[^'"/]*\.wasm(\?[^'"]*)?['"]/;
+
+// 与 Layer 1 一致:扫描前剥注释(避免 dist 里残留的解释性注释/banner 误报)。
+function stripComments(src) {
+  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(?<!:)\/\/[^\n]*/g, '');
+}
+
+function tokensIn(rawContent) {
+  const content = stripComments(rawContent);
+  const hits = [];
+  for (const t of SUBSTRING_TOKENS) if (content.includes(t)) hits.push(t);
+  const m = content.match(WASM_URL_RE);
+  if (m) hits.push(m[0]);
+  return hits;
+}
+
+// dist 模块文件:.js + .mjs/.cjs(防止重运行时藏在非 .js chunk 里绕过)。
+const DIST_MODULE_EXT = /\.(js|mjs|cjs)$/;
+function jsFilesIn(dir, out = []) {
+  if (!existsSync(dir)) return out;
+  for (const e of readdirSync(dir)) {
+    const p = join(dir, e);
+    const s = statSync(p);
+    if (s.isDirectory()) jsFilesIn(p, out);
+    else if (DIST_MODULE_EXT.test(e)) out.push(p);
+  }
+  return out;
+}
+
+// 解析一个 dist 模块的相对 import(构 chunk 依赖图;裸包如 @babylonjs/* 不进图)。
+function relImports(file) {
+  const src = readFileSync(file, 'utf8');
+  const specs = new Set();
+  let m;
+  const re = /\bfrom\s*['"]([^'"]+)['"]/g;
+  while ((m = re.exec(src))) specs.add(m[1]);
+  const side = /\bimport\s*['"]([^'"]+)['"]/g;
+  while ((m = side.exec(src))) specs.add(m[1]);
+  const dyn = /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g;
+  while ((m = dyn.exec(src))) specs.add(m[1]);
+  const resolved = [];
+  for (const spec of specs) {
+    if (!spec.startsWith('.')) continue;
+    const target = resolve(dirname(file), spec);
+    const cands = [target, target + '.js', target + '.mjs', target + '.cjs',
+      join(target, 'index.js'), join(target, 'index.mjs'), join(target, 'index.cjs')];
+    for (const cand of cands) {
+      if (existsSync(cand) && statSync(cand).isFile()) { resolved.push(cand); break; }
+    }
+  }
+  return resolved;
+}
+
+// dist/<dir>/index.{js,mjs,cjs} 取第一个存在的入口。
+function indexEntry(dir) {
+  for (const ext of ['js', 'mjs', 'cjs']) {
+    const p = join(dir, `index.${ext}`);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+function reachableFrom(entry, importGraph) {
+  const seen = new Set();
+  const stack = [entry];
+  while (stack.length) {
+    const f = stack.pop();
+    if (seen.has(f)) continue;
+    seen.add(f);
+    for (const dep of importGraph.get(f) ?? []) if (!seen.has(dep)) stack.push(dep);
+  }
+  return seen;
+}
+
+// ── 主流程 ────────────────────────────────────────────────────────────────────
+if (!existsSync(DIST)) {
+  console.error(`✗ dist 不存在:${DIST}(先 \`pnpm build\`)。`);
+  process.exit(1);
+}
+
+const allJs = jsFilesIn(DIST);
+const importGraph = new Map(allJs.map((f) => [f, relImports(f)]));
+const tokenByFile = new Map();
+for (const f of allJs) {
+  const hits = tokensIn(readFileSync(f, 'utf8'));
+  if (hits.length) tokenByFile.set(f, [...new Set(hits)]);
+}
+
+// 入口 = dist/index.{js,mjs,cjs}(runtime 核心)+ 每个 dist/effects/<id>/index.{js,mjs,cjs}。
+const entries = [];
+const rootIndex = indexEntry(DIST);
+if (rootIndex) entries.push({ label: 'runtime (index)', entry: rootIndex });
+const effectsDist = join(DIST, 'effects');
+if (existsSync(effectsDist)) {
+  for (const id of readdirSync(effectsDist)) {
+    const idx = indexEntry(join(effectsDist, id));
+    if (idx) entries.push({ label: id, entry: idx });
+  }
+}
+
+// 归因:每个入口 → 它可达的、命中 token 的文件。
+const findings = []; // {label, file, tokens}
+const attributedFiles = new Set();
+for (const { label, entry } of entries) {
+  const reach = reachableFrom(entry, importGraph);
+  for (const f of reach) {
+    if (tokenByFile.has(f)) {
+      attributedFiles.add(f);
+      findings.push({ label, file: f, tokens: tokenByFile.get(f) });
+    }
+  }
+}
+// 没被任何入口可达但仍命中的文件(孤儿,理论上不该有)。
+for (const [f, tokens] of tokenByFile) {
+  if (!attributedFiles.has(f)) findings.push({ label: '(未归因/孤儿 chunk)', file: f, tokens });
+}
+
+if (findings.length === 0) {
+  console.log(`✅ Layer 2 dist 禁运行时扫描通过:${allJs.length} 个 js,0 命中(无 meshopt/draco/ktx2/brotli/wasm 运行时)。`);
+  process.exit(0);
+}
+
+console.log(`❌ Layer 2 dist 禁运行时扫描:发现 ${findings.length} 处命中。\n`);
+// 按特效聚合展示
+const byLabel = {};
+for (const f of findings) (byLabel[f.label] ??= []).push(f);
+for (const [label, items] of Object.entries(byLabel)) {
+  console.log(`  特效/入口:${label}`);
+  for (const it of items) {
+    console.log(`    ✗ ${relative(DIST, it.file)}  ←  ${it.tokens.join(', ')}`);
+  }
+}
+console.log('\n修复:定位拉入该运行时的特效(多半是全量 glTF loader / 含 meshopt|draco|ktx2 的 GLB)。');
+console.log('  改用核心 loader、把 GLB 预解压成 plain、或用 ?url 内联的轻量资源。详见 Layer 1 提示与 #2 v0.1.1。');
+process.exit(1);

package/tooling/generate-index.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// 生成顶层 index.json:扫 packages/effects/<id>/,汇总 id/nameZh/kind/category/tags/media。
+// 富检索字段(category/tags/media)优先取 description.json,避免与 manifest 双源。
+import { readdirSync, statSync, readFileSync, writeFileSync, 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 EFFECTS_DIR = join(LIB_ROOT, 'packages', 'effects');
+
+function readJsonSafe(p) {
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+const effects = [];
+for (const entry of readdirSync(EFFECTS_DIR)) {
+  const dir = join(EFFECTS_DIR, entry);
+  if (!statSync(dir).isDirectory()) continue;
+  const indexPath = join(dir, 'index.ts');
+  if (!existsSync(indexPath)) continue;
+
+  const effectJson = readJsonSafe(join(dir, 'effect.json')) ?? {};
+  const desc = readJsonSafe(join(dir, 'description.json')) ?? {};
+  const indexSrc = readFileSync(indexPath, 'utf8');
+  const kind = /createManifestRuntimeEffectPackage|createDataDrivenEffectPackage/.test(indexSrc) ? 'data' : 'code';
+
+  const mediaDir = join(dir, 'media');
+  const media = {};
+  if (existsSync(mediaDir)) {
+    for (const f of readdirSync(mediaDir)) {
+      if (/thumbnail/.test(f)) media.thumbnail = `packages/effects/${entry}/media/${f}`;
+      else if (/preview\.(mp4|webm|gif)$/.test(f)) media.preview = `packages/effects/${entry}/media/${f}`;
+    }
+  }
+
+  effects.push({
+    id: effectJson.id || entry,
+    dir: entry,
+    nameZh: effectJson.nameZh || desc.searchTitleZh || entry,
+    kind,
+    category: desc.semanticTags?.[0] || (effectJson.id?.split('.')[0]) || null,
+    tags: desc.searchKeywordsEn || desc.visualTags || effectJson.search?.tags || [],
+    media,
+    path: `packages/effects/${entry}`,
+  });
+}
+effects.sort((a, b) => a.id.localeCompare(b.id));
+
+const out = {
+  schemaVersion: 'vfx-index/1.0',
+  count: effects.length,
+  effects,
+};
+writeFileSync(join(LIB_ROOT, 'index.json'), JSON.stringify(out, null, 2) + '\n');
+console.log(`✅ index.json 生成:${effects.length} 个特效。`);

package/tooling/test-guardrails.mjs

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