@forgeax/engine-vfx-render 0.1.2

package/src/__tests__/event-resources.unit.test.ts

@@ -0,0 +1,71 @@
+import type { VfxGpuEmitterProgram, VfxGpuTickIntent } from '@forgeax/engine-vfx';
+import { describe, expect, it } from 'vitest';
+import {
+  encodeEventInputs,
+  eventCapacity,
+  eventInputCapacity,
+  VFX_EVENT_INPUT_BYTES,
+} from '../feature/event-resources.js';
+
+const emitter = {
+  id: 'mouth-charge',
+  capacity: 5,
+  backend: { required: 'gpu' },
+  space: 'world',
+  schedule: { rate: 1 },
+  bounds: { kind: 'sphere', center: [0, 0, 0], radius: 1 },
+  renderers: [{ kind: 'billboard', material: 'material-guid' }],
+  channels: [
+    { id: 'impact', capacity: 3, overflow: 'drop-oldest' },
+    { id: 'spark', capacity: 4, overflow: 'drop-newest' },
+  ],
+  events: [
+    {
+      id: 'impact-event',
+      channel: 'impact',
+      subEmitter: 'impact-mesh',
+      fanOut: 2,
+      recursionDepth: 1,
+    },
+  ],
+  simulationWhenCulled: 'continue',
+  wgsl: 'cooked',
+  reflection: {
+    hooks: ['vfx_spawn', 'vfx_update'],
+    imports: [],
+    resources: [],
+    entryPoints: [],
+    bindings: [],
+  },
+} as unknown as VfxGpuEmitterProgram;
+
+describe('GPU event resources', () => {
+  it('derives bounded input and output capacities from reflected channels', () => {
+    expect(eventInputCapacity(emitter)).toBe(7);
+    expect(eventCapacity(emitter)).toBe(5);
+  });
+
+  it('encodes inputs in stable order and fills unused slots with a sentinel', () => {
+    const intent = {
+      emitter,
+      channelInputs: [
+        {
+          channel: 'impact',
+          payload: { position: [1, 2, 3], strength: 0.5 },
+          sequence: 11,
+        },
+      ],
+    } as unknown as VfxGpuTickIntent;
+    const encoded = encodeEventInputs(intent);
+    const view = new DataView(encoded.buffer, encoded.byteOffset, encoded.byteLength);
+
+    expect(encoded.byteLength).toBe(7 * VFX_EVENT_INPUT_BYTES);
+    expect(view.getFloat32(0, true)).toBe(1);
+    expect(view.getFloat32(4, true)).toBe(2);
+    expect(view.getFloat32(8, true)).toBe(3);
+    expect(view.getFloat32(16, true)).toBe(0.5);
+    expect(view.getUint32(20, true)).toBe(11);
+    expect(view.getUint32(28, true)).toBe(2);
+    expect(encoded[32]).toBe(0xff);
+  });
+});

package/src/__tests__/fog-producer.integration.test.ts

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const shaderNames = ['billboard', 'mesh', 'ribbon', 'trail', 'beam'] as const;
+
+function shaderSource(name: (typeof shaderNames)[number]): string {
+  return readFileSync(fileURLToPath(new URL(`../shaders/${name}.wgsl`, import.meta.url)), 'utf8');
+}
+
+function count(source: string, pattern: RegExp): number {
+  return source.match(pattern)?.length ?? 0;
+}
+
+describe('VFX Fog producer contract', () => {
+  it('requires one shared Fog call with a world-space ray for every topology', () => {
+    for (const name of shaderNames) {
+      const source = shaderSource(name);
+      expect(source, name).toMatch(
+        /#import\s+forgeax_view::common::\{[^}]*\bFogViewParams\b[^}]*\bFogRay\b[^}]*\}/,
+      );
+      expect(source, name).toMatch(/#import\s+forgeax_view::fog::\{[^}]*\bapply_fog\b[^}]*\}/);
+      expect(count(source, /\bapply_fog\s*\(/g), name).toBe(1);
+      expect(count(source, /\bFogRay\s*\(/g), name).toBe(1);
+      expect(source, name).toMatch(/world[_A-Za-z]*position|worldPosition/);
+      expect(source, name).toMatch(/ray[_A-Za-z]*distance|distance/);
+      expect(source, name).toMatch(/\.a\b|alpha/);
+      expect(source, name).not.toMatch(/texture_3d|raymarch/i);
+    }
+  });
+
+  it('keeps VFX coverage on the existing reactive graphics lane', () => {
+    const feature = readFileSync(
+      fileURLToPath(new URL('../feature/gpu-particle-feature.ts', import.meta.url)),
+      'utf8',
+    );
+    const camera = readFileSync(
+      fileURLToPath(new URL('../feature/camera.ts', import.meta.url)),
+      'utf8',
+    );
+    expect(feature).toContain("temporalCoverage: 'reactive'");
+    expect(feature).not.toMatch(/fog(?:History|Texture|Registry)/i);
+    expect(feature).toContain('worldPosition');
+    expect(camera).toContain('position');
+    expect(camera).toContain('viewProjection');
+  });
+
+  it('keeps billboard scene-depth soft-particle alpha before Fog mixing', () => {
+    const billboard = shaderSource('billboard');
+    const depthLoad = billboard.indexOf('textureLoad(scene_depth');
+    const softParticleCall = billboard.indexOf('softParticle(input.position');
+    const fogCall = billboard.indexOf('apply_fog(');
+
+    expect(depthLoad).toBeGreaterThanOrEqual(0);
+    expect(softParticleCall).toBeGreaterThan(depthLoad);
+    expect(fogCall).toBeGreaterThan(softParticleCall);
+    expect(billboard).toContain('input.color.a * edge, input.fade_distance');
+  });
+});

package/src/__tests__/gpu-host.integration.test.ts

@@ -0,0 +1,441 @@
+import { createAssetRegistry, createCatalogSource } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { RenderFeaturePreparationFailedError } from '@forgeax/engine-render';
+import { err, ok } from '@forgeax/engine-types';
+import {
+  ParticleEffectPlayer,
+  VFX_GPU_RUNTIME_RESOURCE_KEY,
+  type VfxGpuRuntime,
+  type VfxGpuTickIntent,
+  vfxGpuEffectContribution,
+} from '@forgeax/engine-vfx';
+import { describe, expect, it, vi } from 'vitest';
+import { gpuParticleRenderFeature } from '../feature/gpu-particle-feature.js';
+import {
+  createCameraProvider,
+  createSceneDepthProvider,
+  createVfxRuntimeHost,
+  PARTICLE_SHADER_IDENTIFIERS,
+} from '../index.js';
+
+describe('GPU VFX public host', () => {
+  it('owns loader and FixedUpdate attachment without exposing simulation internals', async () => {
+    const world = new World();
+    const installed: unknown[] = [];
+    const assets = {
+      installDecoder: (kind: unknown, decoder: unknown) => {
+        installed.push({ kind, decoder });
+        return { kind: 'particle-effect', dispose: () => {} };
+      },
+    };
+    const host = createVfxRuntimeHost({
+      camera: {
+        read: () => ({
+          position: new Float32Array(3),
+          right: new Float32Array([1, 0, 0]),
+          up: new Float32Array([0, 1, 0]),
+          viewProjection: new Float32Array(16),
+        }),
+      },
+    });
+
+    const attached = await host.attachWorld({ world, assets: assets as never });
+    expect(attached).toMatchObject({ ok: true, value: { state: 'attached' } });
+    expect(installed).toHaveLength(1);
+    expect(host.feature.requiredMaterialShaders).toEqual(
+      Object.values(PARTICLE_SHADER_IDENTIFIERS),
+    );
+    expect(host.feature.inspect()).toEqual({
+      frameNumber: -1,
+      dispatches: 0,
+      indirectDraws: 0,
+      subjectOutputs: 0,
+    });
+    expect(await host.detachWorld({ world })).toMatchObject({
+      ok: true,
+      value: { state: 'detached' },
+    });
+  });
+
+  it('shares an App-selected GPU decoder when the host attaches the same registry', async () => {
+    const world = new World();
+    const assets = createAssetRegistry({
+      catalog: createCatalogSource({ entries: [] }),
+    });
+    assets.installDecoder(vfxGpuEffectContribution.kind, vfxGpuEffectContribution.decoder);
+    const host = createVfxRuntimeHost({ camera: { read: () => undefined } });
+
+    expect(await host.attachWorld({ world, assets })).toMatchObject({
+      ok: true,
+      value: { state: 'attached' },
+    });
+    expect(await host.detachWorld({ world })).toMatchObject({
+      ok: true,
+      value: { state: 'detached' },
+    });
+    assets.dispose();
+  });
+
+  it('fences preview controls to one attached host generation', async () => {
+    const world = new World();
+    const assets = {
+      installDecoder: () => ({ kind: 'particle-effect', dispose: () => {} }),
+    };
+    const host = createVfxRuntimeHost({ camera: { read: () => undefined } });
+    expect(host.acquireControl(world)).toMatchObject({
+      ok: false,
+      error: { code: 'vfx-host-control-world-detached' },
+    });
+
+    expect(await host.attachWorld({ world, assets: assets as never })).toMatchObject({ ok: true });
+    const acquired = host.acquireControl(world);
+    expect(acquired).toMatchObject({ ok: true, value: { generation: 1 } });
+    if (!acquired.ok) throw new Error(acquired.error.code);
+    const effect = world.allocSharedRef('ParticleEffectAsset', {} as never);
+    const player = world
+      .spawn({
+        component: ParticleEffectPlayer,
+        data: { effect, playing: true, seed: 1, timeScale: 1 },
+      })
+      .unwrap();
+
+    expect(
+      acquired.value.setEmitterSessionEnabled({
+        player,
+        emitterId: 'sparks',
+        enabled: false,
+      }),
+    ).toMatchObject({ ok: true, value: { state: 'disabled', generation: 1 } });
+    expect(
+      world
+        .getResource<VfxGpuRuntime>(VFX_GPU_RUNTIME_RESOURCE_KEY)
+        .isEmitterSessionEnabled(player, 'sparks'),
+    ).toBe(false);
+    expect(acquired.value.replay({ player })).toMatchObject({
+      ok: true,
+      value: { state: 'queued', generation: 1 },
+    });
+    expect(acquired.value.setPlayerRenderConsumption({ player, enabled: false })).toMatchObject({
+      ok: true,
+      value: { state: 'paused', generation: 1 },
+    });
+    expect(acquired.value.setPlayerRenderConsumption({ player, enabled: true })).toMatchObject({
+      ok: true,
+      value: { state: 'enabled', generation: 1 },
+    });
+
+    world.despawn(player).unwrap();
+    expect(acquired.value.replay({ player })).toMatchObject({
+      ok: false,
+      error: {
+        code: 'vfx-host-control-player-unavailable',
+        detail: { player, requestedGeneration: 1, currentGeneration: 1 },
+      },
+    });
+
+    expect(await host.detachWorld({ world })).toMatchObject({ ok: true });
+    expect(await host.attachWorld({ world, assets: assets as never })).toMatchObject({ ok: true });
+    expect(acquired.value.replay({ player })).toMatchObject({
+      ok: false,
+      error: {
+        code: 'vfx-host-control-stale-generation',
+        detail: { requestedGeneration: 1, currentGeneration: 2 },
+      },
+    });
+    expect(host.acquireControl(world)).toMatchObject({ ok: true, value: { generation: 2 } });
+  });
+
+  it('starts every pending emitter program in one prepare frame', () => {
+    const world = new World();
+    const player = world.spawn().unwrap();
+    const intent = (id: string): VfxGpuTickIntent => ({
+      sequence: 1,
+      player,
+      emitter: {
+        id,
+        module: `${id}.vfx.wgsl`,
+        capacity: 4,
+        backend: { required: 'gpu' },
+        space: 'local',
+        simulationWhenCulled: 'continue',
+        schedule: { rate: 0, bursts: [] },
+        bounds: { kind: 'sphere', center: [0, 0, 0], radius: 1 },
+        wgsl: `// ${id}`,
+        reflection: {
+          hooks: ['vfx_spawn', 'vfx_update'],
+          imports: [],
+          resources: [],
+          entryPoints: ['forgeax_vfx_spawn_main'],
+          bindings: [],
+        },
+        renderers: [],
+      },
+      programFingerprint: id,
+      reset: true,
+      fixedDelta: 1 / 60,
+      phaseTick: 0,
+      tick: 0,
+      seed: 1,
+      playCycle: 0,
+      spawnCount: 1,
+      firstParticleId: 0,
+      instanceGeneration: 0,
+      instancePatchCount: 0,
+      parameterBlock: new Uint8Array(),
+      canonicalPayload: new Uint8Array(),
+      replayInput: {
+        seed: 1,
+        tick: 0,
+        generation: 0,
+        sequence: 1,
+        fingerprint: id,
+        payload: new Uint8Array(),
+        values: {},
+        channelInputs: [],
+        droppedCount: 0,
+      },
+      channelInputs: [],
+      eventCounters: {
+        queued: 0,
+        produced: 0,
+        consumed: 0,
+        dropped: 0,
+        overflow: 0,
+        fanOut: 0,
+        recursionDepth: 0,
+        lastSequence: -1,
+      },
+    });
+    const prepareProgram = vi.fn((name: string) =>
+      err(
+        new RenderFeaturePreparationFailedError(
+          'forgeax.vfx-render.gpu-particles',
+          -1,
+          'prepare-gpu-program',
+          'pipeline',
+          name,
+          'rhi-not-available:compile pending',
+          'next-frame',
+        ),
+      ),
+    );
+    const feature = gpuParticleRenderFeature({ camera: { read: () => undefined } });
+
+    const prepared = feature.prepare(
+      {
+        worlds: [
+          {
+            world,
+            runtime: {},
+            camera: {},
+            intents: [intent('first'), intent('second')],
+          },
+        ],
+        frameNumber: 1,
+      } as never,
+      { gpu: { prepareProgram }, targets: [] } as never,
+    );
+
+    expect(prepared).toMatchObject({ ok: false, error: { detail: { recovery: 'next-frame' } } });
+    expect(prepareProgram).toHaveBeenCalledTimes(2);
+    expect(prepareProgram.mock.calls.map(([name]) => name)).toEqual([
+      expect.stringContaining('.first.'),
+      expect.stringContaining('.second.'),
+    ]);
+  });
+
+  it('fences render consumption and keeps masked bindings warm', () => {
+    const world = new World();
+    const player = world.spawn().unwrap();
+    const intent = (tick: number): VfxGpuTickIntent => ({
+      sequence: tick + 1,
+      player,
+      emitter: {
+        id: 'masked',
+        module: 'masked.vfx.wgsl',
+        capacity: 4,
+        backend: { required: 'gpu' },
+        space: 'local',
+        simulationWhenCulled: 'continue',
+        schedule: { rate: 0, bursts: [] },
+        bounds: { kind: 'sphere', center: [0, 0, 0], radius: 1 },
+        wgsl: '// masked',
+        reflection: {
+          hooks: ['vfx_spawn', 'vfx_update'],
+          imports: [],
+          resources: [],
+          entryPoints: ['forgeax_vfx_spawn_main'],
+          bindings: [],
+        },
+        renderers: [],
+      },
+      programFingerprint: 'masked-program',
+      reset: tick === 0,
+      fixedDelta: 1 / 60,
+      phaseTick: tick + 7,
+      tick,
+      seed: 1,
+      playCycle: 0,
+      spawnCount: tick === 0 ? 1 : 0,
+      firstParticleId: 0,
+      instanceGeneration: 0,
+      instancePatchCount: 0,
+      parameterBlock: new Uint8Array(),
+      canonicalPayload: new Uint8Array(),
+      replayInput: {
+        seed: 1,
+        tick,
+        generation: 0,
+        sequence: tick + 1,
+        fingerprint: 'masked-program',
+        payload: new Uint8Array(),
+        values: {},
+        channelInputs: [],
+        droppedCount: 0,
+      },
+      channelInputs: [],
+      eventCounters: {
+        queued: 0,
+        produced: 0,
+        consumed: 0,
+        dropped: 0,
+        overflow: 0,
+        fanOut: 0,
+        recursionDepth: 0,
+        lastSequence: -1,
+      },
+    });
+    let sessionEnabled = true;
+    let renderConsumptionEnabled = true;
+    let generation = 0;
+    const liveBindings = new Set<object>();
+    const prepareProgram = vi.fn(() => ok({ generation: 1 } as never));
+    const prepareBuffer = vi.fn((_name: string, _descriptor: { readonly data?: Uint8Array }) =>
+      ok({ generation: 1 } as never),
+    );
+    const prepareBindings = vi.fn(() => {
+      generation += 1;
+      const reference = { generation: 1, id: generation };
+      liveBindings.add(reference);
+      return ok(reference as never);
+    });
+    const retainBindings = vi.fn((references: readonly object[]) =>
+      references.every((reference) => liveBindings.has(reference))
+        ? ok(undefined)
+        : err(
+            new RenderFeaturePreparationFailedError(
+              'forgeax.vfx-render.gpu-particles',
+              -1,
+              'retain-gpu-bindings',
+              'bindings',
+              'persistent-bindings',
+              'bindings-unavailable',
+              'next-frame',
+            ),
+          ),
+    );
+    const runtime = {
+      hasPlayer: () => true,
+      isEmitterSessionEnabled: () => sessionEnabled,
+      setEmitterCameraVisibility: () => {},
+    };
+    const camera = {
+      position: new Float32Array(3),
+      right: new Float32Array([1, 0, 0]),
+      up: new Float32Array([0, 1, 0]),
+      viewProjection: new Float32Array(16),
+    };
+    const feature = gpuParticleRenderFeature({
+      camera: { read: () => camera },
+      playerConsumption: { isEnabled: () => renderConsumptionEnabled },
+    });
+    const context = {
+      gpu: { prepareProgram, prepareBuffer, prepareBindings, retainBindings },
+      targets: [],
+    } as never;
+    const frame = (intents: readonly VfxGpuTickIntent[], frameNumber: number) =>
+      ({
+        worlds: [{ world, runtime, camera, intents }],
+        frameNumber,
+      }) as never;
+
+    expect(feature.prepare(frame([intent(0)], 1), context).ok).toBe(true);
+    const runtimeWrite = prepareBuffer.mock.calls.find(([name]) => name.includes('.runtime.'))?.[1];
+    expect(runtimeWrite?.data).toBeInstanceOf(Uint8Array);
+    expect(new Uint32Array((runtimeWrite?.data as Uint8Array).buffer)[1]).toBe(7);
+    renderConsumptionEnabled = false;
+    expect(feature.prepare(frame([], 2), context).ok).toBe(true);
+    // Despawned players must not fall back to the retained lastIntent,
+    // otherwise the missing Transform is rendered once at world origin.
+    expect(retainBindings).toHaveBeenCalledTimes(1);
+    renderConsumptionEnabled = true;
+    sessionEnabled = false;
+    expect(feature.prepare(frame([], 3), context).ok).toBe(true);
+    // Session isolation is not a resource lifetime boundary. A paused player
+    // can be re-enabled without a fresh simulation intent, so the masked frame
+    // must keep its prepared bindings warm while contributing no work.
+    expect(retainBindings).toHaveBeenCalledTimes(2);
+    sessionEnabled = true;
+    expect(feature.prepare(frame([], 4), context).ok).toBe(true);
+    expect(retainBindings).toHaveBeenLastCalledWith([expect.objectContaining({ id: generation })]);
+  });
+
+  it('rejects a second host without replacing the first World runtime', async () => {
+    const world = new World();
+    const assets = {
+      installDecoder: () => ({ kind: 'particle-effect', dispose: () => {} }),
+    };
+    const options = {
+      camera: {
+        read: () => undefined,
+      },
+    };
+    const first = createVfxRuntimeHost(options);
+    const second = createVfxRuntimeHost(options);
+    expect(await first.attachWorld({ world, assets: assets as never })).toMatchObject({ ok: true });
+    expect(await second.attachWorld({ world, assets: assets as never })).toMatchObject({
+      ok: false,
+      error: { code: 'vfx-host-world-attach-failed' },
+    });
+    expect(await first.detachWorld({ world })).toMatchObject({ ok: true });
+  });
+
+  it('keeps depth readiness on the host contract for a real renderer frame', () => {
+    const host = createVfxRuntimeHost({
+      camera: { read: () => undefined },
+      providers: [
+        createCameraProvider({ available: () => true }),
+        createSceneDepthProvider({ available: () => true }),
+      ],
+    });
+    const result = host.resolveDataInterfaces({
+      requirements: [
+        {
+          token: 'vfx:scene-depth',
+          kind: 'scene-depth',
+          binding: 9,
+          bindingType: 'sampled-depth',
+          lifetime: 'generation',
+        },
+      ],
+      generation: 1,
+    });
+    expect(result).toMatchObject({ ok: true, value: { readiness: 'ready' } });
+  });
+
+  it('returns an empty keyed inspection aggregate before a player is present', async () => {
+    const world = new World();
+    const assets = {
+      installDecoder: () => ({ kind: 'particle-effect', dispose: () => {} }),
+    };
+    const host = createVfxRuntimeHost({ camera: { read: () => undefined } });
+    await host.attachWorld({ world, assets: assets as never });
+
+    expect(host.inspect(world)).toEqual({
+      generation: 1,
+      renderGeneration: 0,
+      players: [],
+      diagnostics: [],
+    });
+  });
+});

package/src/__tests__/inspect-snapshot.integration.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { createVfxRenderInspectSnapshot } from '../feature/gpu-particle-feature.js';
+
+describe('VFX render inspect projection', () => {
+  it('reports topology counters, stage readiness, provider state, and timing', () => {
+    const snapshot = createVfxRenderInspectSnapshot({
+      topology: 'beam',
+      capacity: 12,
+      produced: 6,
+      dropped: 1,
+      stageReadiness: [{ id: 'turbulence', state: 'ready', generation: 3 }],
+      providerReadiness: { readiness: 'ready', generation: 3 },
+      gpuTiming: { frameMs: 0.8, samples: 8 },
+    });
+
+    expect(snapshot).toEqual(
+      expect.objectContaining({
+        topology: 'beam',
+        counters: { capacity: 12, produced: 6, dropped: 1 },
+        stageReadiness: expect.arrayContaining([expect.objectContaining({ id: 'turbulence' })]),
+        providerReadiness: { readiness: 'ready', generation: 3 },
+        gpuTiming: { frameMs: 0.8, samples: 8 },
+      }),
+    );
+  });
+});

package/src/__tests__/particle-resources.unit.test.ts

@@ -0,0 +1,75 @@
+import type { MaterialAsset, MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  canonicalMeshVertices,
+  particleMaterialPass,
+  particleMaterialUsesBindings,
+  particleMaterialUsesSceneDepth,
+} from '../feature/particle-resources.js';
+
+describe('particle mesh resources', () => {
+  it('preserves authored canonical vertices when the attribute map is empty', () => {
+    const vertices = new Float32Array([
+      0, 1, 0, 0, 1, 0, 0.5, 1, 1, 0, 0, 1, 0, -1, 0, 0, -1, 0, 0.5, 0, 1, 0, 0, 1,
+    ]);
+    const mesh = {
+      vertices,
+      indices: new Uint16Array([0, 1, 0]),
+      attributes: {},
+      submeshes: [],
+    } as unknown as MeshAsset;
+
+    expect(canonicalMeshVertices(mesh)).toBe(vertices);
+  });
+});
+
+describe('particle material pass', () => {
+  it('only requests the shared material bind group for a declared parameter contract', () => {
+    expect(particleMaterialUsesBindings(undefined)).toBe(false);
+    expect(particleMaterialUsesBindings({ kind: 'material', values: {} })).toBe(false);
+    expect(
+      particleMaterialUsesBindings({
+        kind: 'material',
+        parameters: [{ name: 'maskTexture', type: 'texture' }],
+        values: {},
+      }),
+    ).toBe(true);
+  });
+  it('uses the renderer-specific authored shader and render state', () => {
+    const material: MaterialAsset = {
+      kind: 'material',
+      passes: [
+        { name: 'Forward', program: { module: 'game::standard' } },
+        {
+          name: 'particle-billboard',
+          program: { module: 'game::hex-sigil' },
+          renderState: { depthWriteEnabled: false, cullMode: 'none' },
+        },
+      ],
+    };
+
+    expect(particleMaterialPass('billboard', material)).toEqual({
+      shader: 'game::hex-sigil',
+      renderState: { depthWriteEnabled: false, cullMode: 'none' },
+    });
+  });
+
+  it('uses the renderer-owned shader contract for scene-depth selection', () => {
+    expect(particleMaterialUsesSceneDepth('group-0-resource')).toBe(true);
+    expect(particleMaterialUsesSceneDepth('view-with-resource')).toBe(true);
+    expect(particleMaterialUsesSceneDepth('group-0')).toBe(false);
+    expect(particleMaterialUsesSceneDepth('view-only')).toBe(false);
+    expect(particleMaterialUsesSceneDepth('render-material')).toBe(false);
+  });
+
+  it('does not mistake an ordinary Forward pass for a particle shader', () => {
+    const material: MaterialAsset = {
+      kind: 'material',
+      passes: [{ name: 'Forward', program: { module: 'game::standard' } }],
+    };
+
+    expect(particleMaterialPass('mesh', material)).toEqual({
+      shader: 'forgeax::vfx-render.particles.mesh',
+    });
+  });
+});