@forgeax/engine-vfx 0.1.2

package/src/__tests__/instance.unit.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import { createVfxEffectContract } from '../effect-contract.js';
+import { ParticleEffectInstance, type VfxInstanceParent } from '../instance.js';
+
+type Values = {
+  readonly direction: readonly [number, number, number];
+  readonly speed: number;
+};
+
+const reflection = {
+  version: 1,
+  parameters: {
+    name: 'VfxParameters',
+    fields: [
+      { name: 'direction', type: 'vec3<f32>', offset: 0, size: 12, alignment: 16 },
+      { name: 'speed', type: 'f32', offset: 16, size: 4, alignment: 4 },
+    ],
+    size: 32,
+    alignment: 16,
+  },
+  custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+  fingerprint: 'sha256:instance-test',
+} as const;
+
+function createInstance(initialValues: Partial<Values> = {}) {
+  const contract = createVfxEffectContract<Values>(reflection);
+  const parent: VfxInstanceParent<Values> = {
+    fingerprint: reflection.fingerprint,
+    defaults: { direction: [1, 0, 0], speed: 2 },
+  };
+  return new ParticleEffectInstance(contract, { parent, initialValues });
+}
+
+describe('ParticleEffectInstance atomic semantics', () => {
+  it('keeps channel input in the same commit as the parameter generation', () => {
+    const instance = createInstance();
+    const submitted = (
+      instance as unknown as {
+        submit(input: {
+          channel: string;
+          payload: { position: readonly [number, number, number]; strength: number };
+          sequence: number;
+        }): { ok: boolean };
+      }
+    ).submit({ channel: 'impact', payload: { position: [0, 1, 0], strength: 1 }, sequence: 1 });
+
+    expect(submitted.ok).toBe(true);
+    const committed = instance.commit({ seed: 17, tick: 4 });
+    expect(committed.ok).toBe(true);
+    if (!committed.ok) return;
+    expect(committed.value.generation).toBe(0);
+    expect(committed.value.channelInputs).toHaveLength(1);
+  });
+
+  it('merges parent defaults before initial values without copying parent runtime state', () => {
+    const instance = createInstance({ speed: 3 });
+
+    expect(instance.values).toEqual({ direction: [1, 0, 0], speed: 3 });
+    expect(instance.generation).toBe(0);
+  });
+
+  it('coalesces same-tick patches into one generation and one canonical payload', () => {
+    const instance = createInstance();
+
+    expect(instance.patch({ speed: 4 }).ok).toBe(true);
+    expect(instance.patch({ direction: [0, 1, 0] }).ok).toBe(true);
+    expect(instance.generation).toBe(0);
+
+    const committed = instance.commit({ seed: 17, tick: 4 });
+    expect(committed.ok).toBe(true);
+    if (!committed.ok) return;
+    expect(committed.value.generation).toBe(1);
+    expect(committed.value.values).toEqual({ direction: [0, 1, 0], speed: 4 });
+    expect(committed.value.replayInput).toMatchObject({
+      seed: 17,
+      tick: 4,
+      generation: 1,
+    });
+    expect(committed.value.replayInput.payload).toEqual(committed.value.canonicalPayload);
+  });
+
+  it('rejects a bad patch without changing the last valid generation or values', () => {
+    const instance = createInstance();
+    const invalid = JSON.parse('{"direction":[0, 1]}');
+
+    const result = instance.patch(invalid);
+
+    expect(result.ok).toBe(false);
+    expect(instance.generation).toBe(0);
+    expect(instance.values).toEqual({ direction: [1, 0, 0], speed: 2 });
+    expect(instance.pendingPatchCount).toBe(0);
+  });
+
+  it('replays the same seed, tick, generation, and canonical input bytes', () => {
+    const first = createInstance({ speed: 5 });
+    const committed = first.commit({ seed: 9, tick: 12 });
+    expect(committed.ok).toBe(true);
+    if (!committed.ok) return;
+
+    const replay = createInstance({ speed: 5 }).replay(committed.value.replayInput);
+
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) return;
+    expect(replay.value.replayInput).toEqual(committed.value.replayInput);
+    expect([...replay.value.canonicalPayload]).toEqual([...committed.value.canonicalPayload]);
+  });
+});

package/src/__tests__/loader-v1-rejection.unit.test.ts

@@ -0,0 +1,125 @@
+import type { LoadContext } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { particleEffectContribution } from '../assets/particle-effect-decoder.js';
+import { vfxGpuEffectPackLoader } from '../index.js';
+
+const EFFECT_GUID = '019e2cc6-0c86-79da-aa76-b0984c86d45c';
+function context(): LoadContext {
+  return {
+    fetchBinary: async () => {
+      throw new Error('asset-local loaders must not fetch legacy global artifacts');
+    },
+    resolveRef: async () => ({ ok: true, value: 0 }),
+    transcodeCaps: { bc: false, etc2: false, astc: false },
+    device: undefined,
+  };
+}
+
+function input(
+  payload: Record<string, unknown>,
+  artifacts: Record<
+    string,
+    { descriptor: { path: string; mediaType: string }; bytes: Uint8Array }
+  > = {},
+) {
+  return {
+    guid: EFFECT_GUID,
+    kind: 'particle-effect',
+    payload,
+    refs: [],
+    artifacts,
+  };
+}
+
+const validPayload = {
+  kind: 'particle-effect',
+  schemaVersion: 1,
+  emitters: [{ id: 'spark', capacity: 32 }],
+};
+
+describe('vfxGpuEffectPackLoader v2 boundary', () => {
+  it('exposes the cooked particle owner contribution', () => {
+    expect(particleEffectContribution.kind.kind).toBe('particle-effect');
+    expect(particleEffectContribution.consumer).toBe('VfxGpuRuntime');
+  });
+  it('keeps legacy artifact keys outside the v2 asset-local program contract', async () => {
+    const result = await vfxGpuEffectPackLoader.load(
+      input(validPayload, {
+        'effect/program.json': {
+          descriptor: { path: 'program.json', mediaType: 'application/json' },
+          bytes: new TextEncoder().encode('{}'),
+        },
+      }),
+      context(),
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toMatchObject({
+        code: 'vfx-asset-v2-invalid',
+        detail: { path: 'payload' },
+      });
+    }
+  });
+
+  it('rejects a summary-only v2 payload before reading a program artifact', async () => {
+    const result = await vfxGpuEffectPackLoader.load(
+      input({
+        kind: 'particle-effect',
+        schemaVersion: 2,
+        emitters: [],
+        programFingerprint: 'sha256:x',
+      }),
+      context(),
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.detail.path).toBe('payload');
+  });
+
+  it('rejects a v1 package-global artifact shape', async () => {
+    const result = await vfxGpuEffectPackLoader.load(
+      input(validPayload, {
+        'effect/program.json': {
+          descriptor: { path: 'program.json', mediaType: 'application/json' },
+          bytes: new TextEncoder().encode('{}'),
+        },
+      }),
+      context(),
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('vfx-asset-v2-invalid');
+      expect(result.error.detail.path).toBe('payload');
+    }
+  });
+
+  it('rejects raw source fallback when the cooked program is absent', async () => {
+    const result = await vfxGpuEffectPackLoader.load(
+      input({ ...validPayload, source: { emitters: [] }, sourcePath: 'effect.vfx.json' }),
+      context(),
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('vfx-asset-v2-invalid');
+      expect(result.error.detail.path).toBe('payload');
+    }
+  });
+
+  it('keeps the particle owner on the asset-local cooked program contract', async () => {
+    const result = await vfxGpuEffectPackLoader.load(
+      input({
+        kind: 'particle-effect',
+        schemaVersion: 2,
+        emitters: [],
+        programFingerprint: 'sha256:x',
+      }),
+      context(),
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('vfx-asset-v2-invalid');
+  });
+});

package/src/__tests__/player-reflection.unit.test.ts

@@ -0,0 +1,91 @@
+import { World } from '@forgeax/engine-ecs';
+import { componentDefinition, componentSchema } from '@forgeax/engine-ecs/internal';
+import type { Handle, ParticleEffectAsset } from '@forgeax/engine-types';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { ParticleEffectPlayer, type ParticleEffectPlayerData } from '../index.js';
+
+const asset: ParticleEffectAsset = {
+  kind: 'particle-effect',
+  schemaVersion: 2,
+  programFingerprint: 'sha256:test',
+  emitters: [],
+  program: { format: 'forgeax-vfx-program-2', fingerprint: 'sha256:test', emitters: [] },
+};
+
+describe('ParticleEffectPlayer ECS contract', () => {
+  it('exposes exactly the four author-intent fields with stable defaults', () => {
+    expect(Object.keys(componentSchema(ParticleEffectPlayer))).toEqual([
+      'effect',
+      'playing',
+      'seed',
+      'timeScale',
+    ]);
+    expect(componentSchema(ParticleEffectPlayer)).toEqual({
+      effect: 'shared<ParticleEffectAsset>',
+      playing: 'bool',
+      seed: 'u32',
+      timeScale: 'f32',
+    });
+    expect(componentDefinition(ParticleEffectPlayer).defaults).toEqual({
+      playing: true,
+      seed: 0,
+      timeScale: 1,
+    });
+    expect(ParticleEffectPlayer.fields.effect.type).toBe('shared<ParticleEffectAsset>');
+    expect(ParticleEffectPlayer.fields.playing.default).toBe(true);
+    expect(ParticleEffectPlayer.fields.seed.default).toBe(0);
+    expect(ParticleEffectPlayer.fields.timeScale.default).toBe(1);
+  });
+
+  it('round-trips a scene-compatible player payload without changing intent', () => {
+    const world = new World();
+    const effect = world.allocSharedRef('ParticleEffectAsset', asset);
+    const payload: ParticleEffectPlayerData = {
+      effect,
+      playing: false,
+      seed: 42,
+      timeScale: 0.5,
+    };
+    const roundTrip: unknown = JSON.parse(JSON.stringify(payload));
+
+    expect(roundTrip).toEqual(payload);
+  });
+
+  it('uses the shared asset identity in a real spawn and QueryRow loop', () => {
+    const world = new World();
+    const effect = world.allocSharedRef('ParticleEffectAsset', asset);
+    const entity = world
+      .spawn({
+        component: ParticleEffectPlayer,
+        data: { effect, playing: true, seed: 7, timeScale: 0.25 },
+      })
+      .unwrap();
+    const query = world.query({ read: [ParticleEffectPlayer] }).unwrap();
+    let observed = false;
+
+    for (const row of query) {
+      const player = row.get(ParticleEffectPlayer);
+      expectTypeOf(player.effect).toEqualTypeOf<Handle<'ParticleEffectAsset', 'shared'>>();
+      expectTypeOf(player.playing).toBeBoolean();
+      expectTypeOf(player.seed).toBeNumber();
+      expectTypeOf(player.timeScale).toBeNumber();
+      expect(player.effect).toBe(effect);
+      observed = true;
+    }
+
+    expect(entity).toBeDefined();
+    expect(observed).toBe(true);
+  });
+
+  it('keeps the shared-ref data shape assignable to the public handle contract', () => {
+    const world = new World();
+    const effect: Handle<'ParticleEffectAsset', 'shared'> = world.allocSharedRef(
+      'ParticleEffectAsset',
+      asset,
+    );
+    expectTypeOf<ParticleEffectPlayerData['effect']>().toEqualTypeOf<
+      Handle<'ParticleEffectAsset', 'shared'>
+    >();
+    expect(effect).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/player-type.test-d.ts

@@ -0,0 +1,54 @@
+import type { SchemaOf, ShapeOf } from '@forgeax/engine-ecs';
+import type { Handle } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import {
+  createVfxEffectContract,
+  ParticleEffectInstance,
+  type ParticleEffectPlayer,
+  type VfxEffectReflection,
+} from '../index.js';
+
+type Values = {
+  readonly direction: readonly [number, number, number];
+  readonly speed: number;
+};
+
+const reflection: VfxEffectReflection = {
+  version: 1,
+  parameters: { name: 'VfxParameters', fields: [], size: 0, alignment: 1 },
+  custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+  fingerprint: 'sha256:player-type',
+};
+
+describe('ParticleEffectPlayer public type shape', () => {
+  it('infers typed instance patches from the public effect contract', () => {
+    const contract = createVfxEffectContract<Values>(reflection);
+    const instance = new ParticleEffectInstance(contract);
+    instance.patch({ speed: 2, direction: [0, 1, 0] });
+    // @ts-expect-error unknown authored field is rejected at the public SDK boundary
+    instance.patch({ missing: 1 });
+    // @ts-expect-error vector dimensions are part of the generated contract
+    instance.patch({ direction: [0, 1] });
+    expectTypeOf(instance).toMatchTypeOf<ParticleEffectInstance<Values>>();
+  });
+
+  it('contains only the author-intent schema fields', () => {
+    expectTypeOf<keyof SchemaOf<typeof ParticleEffectPlayer>>().toEqualTypeOf<
+      'effect' | 'playing' | 'seed' | 'timeScale'
+    >();
+    expectTypeOf<
+      SchemaOf<typeof ParticleEffectPlayer>['effect']
+    >().toEqualTypeOf<'shared<ParticleEffectAsset>'>();
+    expectTypeOf<SchemaOf<typeof ParticleEffectPlayer>['playing']>().toEqualTypeOf<'bool'>();
+    expectTypeOf<SchemaOf<typeof ParticleEffectPlayer>['seed']>().toEqualTypeOf<'u32'>();
+    expectTypeOf<SchemaOf<typeof ParticleEffectPlayer>['timeScale']>().toEqualTypeOf<'f32'>();
+  });
+
+  it('derives the shared effect handle from the ECS schema', () => {
+    type Data = ShapeOf<SchemaOf<typeof ParticleEffectPlayer>>;
+    expectTypeOf<Data['effect']>().toEqualTypeOf<Handle<'ParticleEffectAsset', 'shared'>>();
+    expectTypeOf<Data['playing']>().toEqualTypeOf<boolean>();
+    expectTypeOf<Data['seed']>().toEqualTypeOf<number>();
+    expectTypeOf<Data['timeScale']>().toEqualTypeOf<number>();
+  });
+});

package/src/__tests__/renderer-source.unit.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { parseParticleEffectSourceV2 } from '../code-source.js';
+
+const rendererSource = (renderer: unknown) => ({
+  schemaVersion: 2,
+  emitters: [
+    {
+      id: 'showcase',
+      capacity: 64,
+      backend: { required: 'gpu' },
+      space: 'world',
+      bounds: { kind: 'sphere', center: [0, 0, 0], radius: 4 },
+      schedule: { rate: 4 },
+      program: { module: 'forgeax_vfx::default' },
+      renderers: [renderer],
+    },
+  ],
+});
+
+describe('Batch B renderer source contract', () => {
+  it.each([
+    ['billboard', { kind: 'billboard', material: 'vfx', sorting: 'emitter' }],
+    ['ribbon', { kind: 'ribbon', material: 'vfx', stripKey: 'alive-index', capacity: 32 }],
+    ['trail', { kind: 'trail', material: 'vfx', historyLength: 8, capacity: 32 }],
+    ['beam', { kind: 'beam', material: 'vfx', endpointField: 'velocity', capacity: 16 }],
+  ])('parses the independent %s topology', (_kind, renderer) => {
+    const parsed = parseParticleEffectSourceV2(rendererSource(renderer));
+
+    expect(parsed.ok).toBe(true);
+    if (parsed.ok) expect(parsed.value.emitters[0]?.renderers[0]).toMatchObject(renderer);
+  });
+
+  it('rejects zero topology capacity instead of silently disabling output', () => {
+    const parsed = parseParticleEffectSourceV2(
+      rendererSource({ kind: 'trail', material: 'vfx', historyLength: 8, capacity: 0 }),
+    );
+
+    expect(parsed).toMatchObject({
+      ok: false,
+      error: { code: 'vfx-source-renderer-invalid' },
+    });
+  });
+
+  it('keeps an explicitly disabled renderer distinguishable from an empty list', () => {
+    const parsed = parseParticleEffectSourceV2(
+      rendererSource({
+        kind: 'ribbon',
+        material: 'vfx',
+        stripKey: 'alive-index',
+        capacity: 32,
+        enabled: false,
+      }),
+    );
+
+    expect(parsed).toMatchObject({ ok: true });
+    if (parsed.ok) expect(parsed.value.emitters[0]?.renderers[0]).toMatchObject({ enabled: false });
+  });
+});

package/src/__tests__/replay-canonical.unit.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { createVfxEffectContract } from '../effect-contract.js';
+import { ParticleEffectInstance } from '../instance.js';
+
+type Values = {
+  readonly zeta: number;
+  readonly alpha: readonly [number, number, number];
+};
+
+const reflection = {
+  version: 1,
+  parameters: {
+    name: 'VfxParameters',
+    fields: [
+      { name: 'zeta', type: 'f32', offset: 0, size: 4, alignment: 4 },
+      { name: 'alpha', type: 'vec3<f32>', offset: 16, size: 12, alignment: 16 },
+    ],
+    size: 32,
+    alignment: 16,
+  },
+  custom: { name: 'VfxCustom', fields: [], size: 0, alignment: 1 },
+  fingerprint: 'sha256:canonical-test',
+} as const;
+
+function makeInstance(values: Partial<Values> = {}) {
+  return new ParticleEffectInstance(createVfxEffectContract<Values>(reflection), {
+    initialValues: { zeta: 0.1, alpha: [0.2, 0.3, 0.4], ...values },
+  });
+}
+
+describe('VFX canonical replay payload', () => {
+  it('uses stable field order and f32-normalized scalar/vector values', () => {
+    const first = makeInstance({ zeta: 0.1 });
+    const second = makeInstance({ zeta: Math.fround(0.1) });
+
+    const left = first.commit({ seed: 5, tick: 8 });
+    const right = second.commit({ seed: 5, tick: 8 });
+
+    expect(left.ok).toBe(true);
+    expect(right.ok).toBe(true);
+    if (!left.ok || !right.ok) return;
+    expect([...left.value.canonicalPayload]).toEqual([...right.value.canonicalPayload]);
+    expect(new TextDecoder().decode(left.value.canonicalPayload)).toContain('alpha');
+    expect(new TextDecoder().decode(left.value.canonicalPayload).indexOf('alpha')).toBeLessThan(
+      new TextDecoder().decode(left.value.canonicalPayload).indexOf('zeta'),
+    );
+  });
+
+  it('encodes empty patches and multiple patches as one deterministic generation', () => {
+    const first = makeInstance();
+    const second = makeInstance();
+    expect(first.patch({}).ok).toBe(true);
+    expect(first.patch({ zeta: 2 }).ok).toBe(true);
+    expect(second.patch({ zeta: 2 }).ok).toBe(true);
+    expect(second.patch({}).ok).toBe(true);
+
+    const left = first.commit({ seed: 11, tick: 13 });
+    const right = second.commit({ seed: 11, tick: 13 });
+
+    expect(left.ok).toBe(true);
+    expect(right.ok).toBe(true);
+    if (!left.ok || !right.ok) return;
+    expect(left.value.generation).toBe(1);
+    expect(left.value.patchCount).toBe(2);
+    expect(left.value.replayInput).toEqual(right.value.replayInput);
+    expect([...left.value.parameterBlock]).toEqual([...right.value.parameterBlock]);
+  });
+});

package/src/__tests__/runtime-dist-isolation.test.ts

@@ -0,0 +1,100 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const vfxRoot = resolve(import.meta.dirname, '..', '..');
+const compilerRoot = resolve(vfxRoot, '..', 'vfx-compiler');
+
+function readJson(path: string): unknown {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (!isRecord(value)) throw new Error('expected a JSON object');
+  return value;
+}
+
+function sourceFiles(root: string): string[] {
+  const files: string[] = [];
+  for (const entry of readdirSync(root)) {
+    if (entry === '__tests__') continue;
+    const path = resolve(root, entry);
+    if (statSync(path).isDirectory()) {
+      files.push(...sourceFiles(path));
+    } else if (path.endsWith('.ts')) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+
+function sourceText(root: string): string {
+  return sourceFiles(resolve(root, 'src'))
+    .map((path) => readFileSync(path, 'utf8'))
+    .join('\n');
+}
+
+function dependencyNames(manifest: unknown): readonly string[] {
+  const value = record(manifest);
+  const dependencies = value.dependencies;
+  return dependencies === undefined ? [] : Object.keys(record(dependencies));
+}
+
+const runtimeForbiddenDependencies = [
+  '@forgeax/engine-vfx-compiler',
+  '@forgeax/engine-shader-compiler',
+  '@forgeax/engine-naga',
+  '@forgeax/engine-render',
+  '@forgeax/engine-rhi',
+];
+
+const compilerForbiddenDependencies = [
+  '@forgeax/engine-assets-runtime',
+  '@forgeax/engine-ecs',
+  '@forgeax/engine-render',
+  '@forgeax/engine-rhi',
+  '@forgeax/engine-naga',
+];
+
+describe('VFX runtime/compiler physical boundary', () => {
+  it('keeps forbidden packages out of both production dependency manifests', () => {
+    const runtimeDependencies = dependencyNames(readJson(resolve(vfxRoot, 'package.json')));
+    const compilerDependencies = dependencyNames(readJson(resolve(compilerRoot, 'package.json')));
+
+    for (const dependency of runtimeForbiddenDependencies) {
+      expect(runtimeDependencies).not.toContain(dependency);
+    }
+    for (const dependency of compilerForbiddenDependencies) {
+      expect(compilerDependencies).not.toContain(dependency);
+    }
+  });
+
+  it('keeps compiler and device symbols out of the built runtime entry', () => {
+    const runtimeDist = readFileSync(resolve(vfxRoot, 'dist', 'index.mjs'), 'utf8');
+    const runtimeDeclarations = readFileSync(resolve(vfxRoot, 'dist', 'index.d.ts'), 'utf8');
+    const compilerDist = readFileSync(resolve(compilerRoot, 'dist', 'index.mjs'), 'utf8');
+
+    expect(runtimeDist).not.toMatch(/engine-vfx-compiler|shader-compiler|engine-naga/);
+    expect(runtimeDist).not.toMatch(
+      /\b(?:RenderFeature|Renderer|RenderGraph|GPUDevice|RhiDevice)\b/,
+    );
+    expect(runtimeDeclarations).not.toMatch(/engine-vfx-compiler|shader-compiler|engine-naga/);
+    expect(compilerDist).not.toMatch(/engine-ecs|engine-render|engine-rhi|engine-naga/);
+    expect(compilerDist).not.toMatch(
+      /\b(?:World|RenderFeature|Renderer|RenderGraph|GPUDevice|RhiDevice)\b/,
+    );
+  });
+
+  it('does not hide the boundary behind a source-level optional import', () => {
+    const runtimeSource = sourceText(vfxRoot);
+    const compilerSource = sourceText(compilerRoot);
+
+    expect(runtimeSource).not.toMatch(/engine-vfx-compiler|engine-shader-compiler|engine-naga/);
+    expect(compilerSource).not.toMatch(/engine-ecs|engine-render|engine-rhi/);
+    expect(runtimeSource).not.toMatch(/import\s*\(.*compiler|import\s*\(.*naga/s);
+  });
+});

package/src/__tests__/scriptable-pack-consumer.test-d.ts

@@ -0,0 +1,9 @@
+import type { Handle, ParticleEffectAsset } from '@forgeax/engine-types';
+import { expectTypeOf, it } from 'vitest';
+
+it('keeps the loaded particle program and World handle boundary typed', () => {
+  expectTypeOf<ParticleEffectAsset['program']>().toMatchTypeOf<ParticleEffectAsset['program']>();
+  expectTypeOf<Handle<'ParticleEffectAsset', 'shared'>>().toEqualTypeOf<
+    Handle<'ParticleEffectAsset', 'shared'>
+  >();
+});

package/src/__tests__/stage-source.unit.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { parseVfxStageDeclarations } from '../code-source.js';
+
+describe('VFX stage source declarations', () => {
+  it('discovers a bounded particle stage with explicit resource access', () => {
+    const result = parseVfxStageDeclarations(
+      '// #vfx stage turbulence entry=vfx_turbulence domain=particle resources=particles:read-write,runtime:read dependsOn=update iterationBudget=4',
+    );
+
+    expect(result).toEqual({
+      ok: true,
+      value: [
+        {
+          id: 'turbulence',
+          entry: 'vfx_turbulence',
+          domain: 'particle',
+          resources: [
+            { name: 'particles', access: 'read-write' },
+            { name: 'runtime', access: 'read' },
+          ],
+          dependsOn: ['update'],
+          iterationBudget: 4,
+        },
+      ],
+    });
+  });
+
+  it.each([
+    ['domain', 'domain=render'],
+    ['resource', 'resources=privateBuffer:read'],
+    ['entry', 'entry=forgeax_vfx_update_main'],
+    ['budget', 'iterationBudget=0'],
+  ])('rejects an invalid stage %s with a recovery hint', (_name, replacement) => {
+    const result = parseVfxStageDeclarations(
+      `// #vfx stage turbulence entry=vfx_turbulence domain=particle resources=particles:read-write dependsOn=none iterationBudget=4`.replace(
+        replacement.startsWith('domain=')
+          ? 'domain=particle'
+          : replacement.startsWith('resources=')
+            ? 'resources=particles:read-write'
+            : replacement.startsWith('entry=')
+              ? 'entry=vfx_turbulence'
+              : 'iterationBudget=4',
+        replacement,
+      ),
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('vfx-source-stage-invalid');
+      expect(result.error.hint).toContain('recook');
+      expect(result.error.detail.path).toContain('turbulence');
+    }
+  });
+
+  it('rejects unknown directive fields and duplicate stage ids', () => {
+    const result = parseVfxStageDeclarations(`
+      // #vfx stage turbulence entry=vfx_turbulence domain=particle resources=particles:read-write dependsOn=none iterationBudget=4 extra=yes
+      // #vfx stage turbulence entry=vfx_turbulence domain=particle resources=particles:read-write dependsOn=none iterationBudget=4
+    `);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.expected).toContain('supported stage declaration');
+  });
+});