@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/__tests__/surface-configuration.unit.test.ts

@@ -0,0 +1,91 @@
+import type { RhiCanvasContext, RhiDevice } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
+import { configureSurface, resolveSurfaceFormatPair } from '../render-system';
+
+function device(backendKind: 'webgpu' | 'wgpu-webgl2', storageBuffer = false): RhiDevice {
+  return {
+    limits: { maxStorageBuffersPerShaderStage: 0 },
+    caps: { backendKind, storageBuffer },
+  } as unknown as RhiDevice;
+}
+
+describe('configureSurface', () => {
+  it('projects the configured surface format into graph topology without reinterpretation drift', () => {
+    expect(resolveSurfaceFormatPair('webgpu', 'bgra8unorm', 'bgra8unorm-srgb')).toEqual({
+      storage: 'bgra8unorm',
+      view: 'bgra8unorm-srgb',
+    });
+    expect(resolveSurfaceFormatPair('wgpu-webgl2', 'rgba8unorm', 'rgba8unorm-srgb')).toEqual({
+      storage: 'rgba8unorm-srgb',
+      view: 'rgba8unorm-srgb',
+    });
+  });
+
+  it('keeps native WebGPU sRGB view support when texture binding is available', () => {
+    const configure = vi.fn(() => ok(undefined));
+    const context = { configure } as unknown as RhiCanvasContext;
+    const webGpuDevice = device('webgpu', true);
+    const result = configureSurface(context, webGpuDevice, 'bgra8unorm', 'bgra8unorm-srgb');
+    expect(result.ok).toBe(true);
+    expect(configure).toHaveBeenCalledWith({
+      device: webGpuDevice,
+      format: 'bgra8unorm',
+      alphaMode: 'premultiplied',
+      usage: 0x10 | 0x04 | 0x01,
+      viewFormats: ['bgra8unorm-srgb'],
+    });
+  });
+
+  it('keeps COPY_SRC on a low-capability WebGPU surface', () => {
+    const configure = vi.fn(() => ok(undefined));
+    const context = { configure } as unknown as RhiCanvasContext;
+    const webGpuDevice = device('webgpu');
+    const result = configureSurface(context, webGpuDevice, 'bgra8unorm', 'bgra8unorm-srgb');
+    expect(result.ok).toBe(true);
+    expect(configure).toHaveBeenCalledWith({
+      device: webGpuDevice,
+      format: 'bgra8unorm',
+      alphaMode: 'premultiplied',
+      usage: 0x10 | 0x01,
+      viewFormats: ['bgra8unorm-srgb'],
+    });
+  });
+
+  it('keeps the wgpu WebGL2 surface COLOR_TARGET-only', () => {
+    const configure = vi.fn(() => ok(undefined));
+    const context = { configure } as unknown as RhiCanvasContext;
+    const webGlDevice = device('wgpu-webgl2');
+    const result = configureSurface(context, webGlDevice, 'rgba8unorm', 'rgba8unorm-srgb');
+    expect(result.ok).toBe(true);
+    expect(configure).toHaveBeenCalledWith({
+      device: webGlDevice,
+      format: 'rgba8unorm-srgb',
+      alphaMode: 'opaque',
+      usage: 0x10,
+    });
+    const descriptor = (configure.mock.calls[0] as unknown as [Record<string, unknown>])[0];
+    expect(descriptor).not.toHaveProperty('viewFormats');
+  });
+
+  it('uses the capability gate when WebGL2 reports a translated storage limit', () => {
+    const configure = vi.fn(() => ok(undefined));
+    const context = { configure } as unknown as RhiCanvasContext;
+    const webGlDevice = {
+      limits: { maxStorageBuffersPerShaderStage: 8 },
+      caps: { backendKind: 'wgpu-webgl2', storageBuffer: false },
+    } as unknown as RhiDevice;
+
+    const result = configureSurface(context, webGlDevice, 'rgba8unorm', 'rgba8unorm-srgb');
+
+    expect(result.ok).toBe(true);
+    expect(configure).toHaveBeenCalledWith({
+      device: webGlDevice,
+      format: 'rgba8unorm-srgb',
+      alphaMode: 'opaque',
+      usage: 0x10,
+    });
+    const descriptor = (configure.mock.calls[0] as unknown as [Record<string, unknown>])[0];
+    expect(descriptor).not.toHaveProperty('viewFormats');
+  });
+});

package/src/__tests__/texture-usage-surface.unit.test.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
+
+const ownerSource = readFileSync(new URL('../gpu-texture-usage.ts', import.meta.url), 'utf8');
+const consumerSources = [
+  readFileSync(new URL('../render-data.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../shadow-atlas.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../ssao-buffers.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../device/gpu-residency.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../ibl/IblPipelineCache.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../ibl/skylight-bind-group.ts', import.meta.url), 'utf8'),
+];
+
+describe('texture usage owner', () => {
+  it('keeps the four texture usage bits in one owner', () => {
+    expect(GPU_TEXTURE_USAGE_COPY_SRC).toBe(0x01);
+    expect(GPU_TEXTURE_USAGE_COPY_DST).toBe(0x02);
+    expect(GPU_TEXTURE_USAGE_TEXTURE_BINDING).toBe(0x04);
+    expect(GPU_TEXTURE_USAGE_RENDER_ATTACHMENT).toBe(0x10);
+    expect(GPU_TEXTURE_USAGE_RENDER_ATTACHMENT_AND_TEXTURE_BINDING).toBe(0x14);
+    expect(ownerSource.match(/export const GPU_TEXTURE_USAGE_/g)).toHaveLength(5);
+  });
+
+  it('routes texture usage consumers through the owner', () => {
+    for (const source of consumerSources) {
+      expect(source).toContain('gpu-texture-usage');
+      expect(source).not.toMatch(/const GPU_TEXTURE_USAGE_[A-Z_]+\s*=/);
+      expect(source).not.toMatch(
+        /const (TEXTURE_BINDING_USAGE|TEXTURE_COPY_DST_USAGE|TEXTURE_COPY_SRC_USAGE|RENDER_ATTACHMENT_USAGE)\s*=/,
+      );
+      expect(source).not.toMatch(
+        /GPU_TEXTURE_USAGE_(RENDER_ATTACHMENT|TEXTURE_BINDING)\s*\|\s*GPU_TEXTURE_USAGE_(RENDER_ATTACHMENT|TEXTURE_BINDING)/,
+      );
+    }
+  });
+
+  it('keeps typed pipelines on graph access declarations instead of physical usage bits', async () => {
+    const graphOwners = await Promise.all([
+      readFileSync(new URL('../pipeline/standard-forward-lane.ts', import.meta.url), 'utf8'),
+      readFileSync(new URL('../pipeline/standard-pipeline.ts', import.meta.url), 'utf8'),
+      readFileSync(new URL('../typed-shadow-passes.ts', import.meta.url), 'utf8'),
+    ]);
+    for (const source of graphOwners) {
+      expect(source).not.toMatch(/usage:\s*0x[0-9a-f]+/i);
+    }
+    expect(graphOwners.join('\n')).toMatch(
+      /usage: '(?:color-attachment|depth-stencil-write|storage-write)'/,
+    );
+    expect(graphOwners[2]).toContain('gpu-texture-usage');
+  });
+});

package/src/__tests__/typed-pipeline-topology.unit.test.ts

@@ -0,0 +1,223 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { standardPipeline } from '../pipeline/standard-pipeline';
+import { DEFAULT_STANDARD_PROFILE } from '../pipeline/standard-profile';
+import type {
+  RenderPipeline,
+  RenderPipelineFrame,
+  RenderPipelineTopology,
+} from '../render-pipeline';
+
+let device: RhiDevice;
+
+beforeAll(async () => {
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) throw adapter.error;
+  const created = await adapter.value.requestDevice();
+  if (!created.ok) throw created.error;
+  device = created.value;
+});
+
+function topology(
+  pipelineId: 'forgeax::standard',
+  overrides: Partial<RenderPipelineTopology> = {},
+): RenderPipelineTopology {
+  return {
+    pipelineId,
+    config: undefined,
+    surface: {
+      width: 800,
+      height: 600,
+      storageFormat: 'bgra8unorm',
+      viewFormat: 'bgra8unorm-srgb',
+    },
+    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'on' },
+    shadow: {
+      mapSize: 1024,
+      cascadeCount: 4,
+      pointCount: 1,
+      pointFaceSize: 512,
+      spotCount: 1,
+    },
+    lane: {
+      compute: true,
+      storageBuffer: true,
+      multisample: true,
+      maxColorAttachments: 8,
+    },
+    featureTopologySignature: 'none',
+    gpuDrivenTopologySignature: '',
+    ...overrides,
+  };
+}
+
+function compile(pipeline: RenderPipeline, input: RenderPipelineTopology) {
+  const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+  const built = pipeline.build(
+    {
+      graph,
+      projectGpuDriven: () => ok(undefined),
+      contributeFeatures: () => ok(undefined),
+    },
+    input,
+  );
+  if (!built.ok) return built;
+  return graph.compile({
+    device,
+    surfaceSize: { width: input.surface.width, height: input.surface.height },
+  });
+}
+
+describe('typed built-in pipeline topology', () => {
+  it('orders HDRP compute, shadow, deferred, SSAO, forward, observation, and output work', () => {
+    const compiled = compile(
+      standardPipeline,
+      topology('forgeax::standard', {
+        standardProfile: { ...DEFAULT_STANDARD_PROFILE, lighting: 'clustered', ssao: true },
+      }),
+    );
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const info = compiled.value.inspect();
+    const names = info.passes.map((pass) => pass.name);
+    const ordered = [
+      'cluster-membership-producer',
+      'g-buffer',
+      'ssao-calc',
+      'ssao-blur',
+      'lighting',
+      'forward',
+      'linear-hdr-observation',
+      'tonemap',
+    ];
+    for (let index = 1; index < ordered.length; index += 1) {
+      expect(names.indexOf(ordered[index] ?? '')).toBeGreaterThan(
+        names.indexOf(ordered[index - 1] ?? ''),
+      );
+    }
+    expect(names.filter((name) => name.startsWith('point-shadow-'))).toHaveLength(6);
+    expect(names.filter((name) => name.startsWith('shadowCascade'))).toHaveLength(4);
+
+    const membership = info.passes.find((pass) => pass.name === 'cluster-membership-producer');
+    expect(membership?.kind).toBe('compute');
+    expect(membership?.accesses).toContainEqual({
+      resource: 'hdrp-light-index-list',
+      usage: 'storage-write',
+    });
+    const lighting = info.passes.find((pass) => pass.name === 'lighting');
+    expect(lighting?.accesses).toEqual(
+      expect.arrayContaining([
+        { resource: 'gbuffer-normal-roughness', usage: 'sampled-read' },
+        { resource: 'gbuffer-albedo-metallic', usage: 'sampled-read' },
+        { resource: 'gbuffer-emissive-ao', usage: 'sampled-read' },
+        { resource: 'ssao-blurred', usage: 'sampled-read' },
+        { resource: 'hdrp-scene-color', usage: 'color-attachment' },
+      ]),
+    );
+  });
+
+  it('omits SSAO and compute membership on the bounded fallback lane', () => {
+    const compiled = compile(
+      standardPipeline,
+      topology('forgeax::standard', {
+        standardProfile: { ...DEFAULT_STANDARD_PROFILE, lighting: 'clustered' },
+        config: { ssao: { enabled: false } },
+        lane: {
+          compute: false,
+          storageBuffer: false,
+          multisample: false,
+          maxColorAttachments: 8,
+        },
+      }),
+    );
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const names = compiled.value.inspect().passes.map((pass) => pass.name);
+    expect(names).not.toContain('cluster-membership-producer');
+    expect(names.some((name) => name.startsWith('ssao-'))).toBe(false);
+  });
+
+  it('keeps URP post effects after output and before debug overlay', () => {
+    const compiled = compile(
+      standardPipeline,
+      topology('forgeax::standard', {
+        config: { postEffects: ['example::a', 'example::b'] },
+      }),
+    );
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const info = compiled.value.inspect();
+    const names = info.passes.map((pass) => pass.name);
+    expect(names.filter((name) => name.startsWith('shadowCascade'))).toHaveLength(4);
+    expect(names.indexOf('post-effect-0')).toBeGreaterThan(names.indexOf('fxaa'));
+    expect(names.indexOf('post-effect-1')).toBeGreaterThan(names.indexOf('post-effect-0'));
+    expect(names.indexOf('debug-overlay')).toBeGreaterThan(names.indexOf('post-effect-1'));
+    expect(info.resources.map((resource) => resource.label)).toEqual(
+      expect.arrayContaining([
+        'post-effect-scratch-0',
+        'post-effect-output-0',
+        'post-effect-scratch-1',
+      ]),
+    );
+    const copy0 = info.passes.find((pass) => pass.name === 'post-effect-copy-0');
+    const effect0 = info.passes.find((pass) => pass.name === 'post-effect-0');
+    const copy1 = info.passes.find((pass) => pass.name === 'post-effect-copy-1');
+    const effect1 = info.passes.find((pass) => pass.name === 'post-effect-1');
+    expect(copy0?.accesses).toContainEqual({ resource: 'surface', usage: 'copy-src' });
+    expect(copy1?.accesses).toContainEqual({
+      resource: 'post-effect-output-0',
+      usage: 'copy-src',
+    });
+    expect(effect0?.accesses).toContainEqual({
+      resource: 'post-effect-output-0',
+      usage: 'color-attachment',
+    });
+    expect(effect1?.accesses).toContainEqual({
+      resource: 'surface',
+      usage: 'color-attachment',
+    });
+    expect(copy1?.dependencies).toContain('post-effect-0');
+    expect(effect1?.dependencies).toContain('post-effect-copy-1');
+  });
+
+  it('removes unsupported MSAA and composite post work on the fallback lane', () => {
+    const compiled = compile(
+      standardPipeline,
+      topology('forgeax::standard', {
+        camera: { tonemap: 'none', antialias: 'msaa', bloom: 'off' },
+        config: { postEffects: ['example::a'] },
+        lane: {
+          compute: false,
+          storageBuffer: false,
+          multisample: false,
+          maxColorAttachments: 4,
+        },
+      }),
+    );
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const info = compiled.value.inspect();
+    expect(info.resources.some((resource) => resource.label.includes('msaa'))).toBe(false);
+    expect(info.passes.some((pass) => pass.name.startsWith('post-effect-'))).toBe(false);
+  });
+
+  it('returns a structured HDRP capability refusal before graph compilation', () => {
+    const built = compile(
+      standardPipeline,
+      topology('forgeax::standard', {
+        standardProfile: { ...DEFAULT_STANDARD_PROFILE, lighting: 'clustered' },
+        lane: {
+          compute: true,
+          storageBuffer: true,
+          multisample: true,
+          maxColorAttachments: 3,
+        },
+      }),
+    );
+    expect(built.ok).toBe(false);
+    if (!built.ok) expect(built.error.code).toBe('hdrp-deferred-caps-insufficient');
+  });
+});

package/src/__tests__/urp-pipeline-targets.unit.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { resolveStandardRenderFeatureTargets } from '../features/targets';
+
+function targets(
+  tonemap: 'none' | 'aces-filmic',
+  antialias: 'none' | 'fxaa' | 'msaa',
+  storageBuffer: boolean,
+) {
+  return resolveStandardRenderFeatureTargets({
+    tonemap,
+    antialias,
+    colorAttachmentFormat: 'bgra8unorm-srgb',
+    storageBuffer,
+    multisample: true,
+  });
+}
+
+describe('urp render feature targets', () => {
+  it('publishes the linear-LDR target used by native no-tonemap frames', () => {
+    expect(targets('none', 'none', true)?.[0]).toMatchObject({
+      kind: 'scene-color',
+      format: 'rgba16float',
+      sampleCount: 1,
+    });
+  });
+
+  it('publishes the MSAA linear-LDR target with the graph sample count', () => {
+    expect(targets('none', 'msaa', true)?.[0]).toMatchObject({
+      kind: 'scene-color',
+      format: 'rgba16float',
+      sampleCount: 4,
+    });
+  });
+
+  it('keeps the surface target for non-storage-buffer LDR frames', () => {
+    expect(targets('none', 'none', false)?.[0]).toMatchObject({
+      kind: 'scene-color',
+      format: 'bgra8unorm-srgb',
+      sampleCount: 1,
+    });
+  });
+});

package/src/__tests__/urp-pipeline.unit.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { resolvePostColorDomainContract } from '../render-pipeline';
+
+describe('Standard forward post color-domain order', () => {
+  it('declares the required linear-to-encoded stage sequence', () => {
+    expect(resolvePostColorDomainContract('linear-ldr')).toEqual([
+      ['transparent-blend', 'linear-ldr', 'linear-ldr'],
+      ['bloom', 'linear-hdr', 'linear-hdr'],
+      ['tone', 'linear-hdr', 'linear-ldr'],
+      ['fxaa', 'linear-ldr', 'linear-ldr'],
+      ['output', 'linear-ldr', 'display-encoded'],
+    ]);
+  });
+});

package/src/__tests__/vertex-color-pipeline.unit.test.ts

@@ -0,0 +1,132 @@
+import {
+  deriveVertexLayoutProjection,
+  packInterleavedVertexAttributes,
+} from '@forgeax/engine-geometry';
+import type { VertexAttributeMap } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  buildPipelineDescriptor,
+  cacheKeyOf,
+  type PipelineSpec,
+  variantSetFromVertexLayoutProjection,
+} from '../pipeline-spec';
+
+const baseAttributes = (): VertexAttributeMap => ({
+  position: new Float32Array([0, 0, 0]),
+  normal: new Float32Array([0, 1, 0]),
+  uv: new Float32Array([0, 0]),
+  tangent: new Float32Array([1, 0, 0, 1]),
+});
+
+function spec(
+  vertexLayout: VertexAttributeMap,
+  projection = deriveVertexLayoutProjection(vertexLayout),
+): PipelineSpec {
+  return {
+    shader: {
+      id: 'forgeax::default-standard-pbr',
+      passKind: 'forward',
+      variantSet: 'VERTEX_COLOR_AVAILABLE=false',
+    },
+    attachments: { colorFormats: ['rgba8unorm'], depthFormat: 'depth24plus', sampleCount: 1 },
+    geometry: { topology: 'triangle-list', vertexLayout, vertexLayoutProjection: projection },
+    renderState: undefined,
+  };
+}
+
+describe('render vertex-color projection contract', () => {
+  it('builds the GPU vertex descriptor from the immutable projection, not a parallel map', () => {
+    const plain = baseAttributes();
+    const coloredProjection = deriveVertexLayoutProjection({
+      ...plain,
+      color: new Float32Array([1, 1, 1, 1]),
+    });
+    const descriptor = buildPipelineDescriptor(spec(plain, coloredProjection), {
+      vertex: 'vertex-module',
+      fragment: 'fragment-module',
+    });
+    expect(descriptor.vertex).toMatchObject({
+      buffers: [
+        {
+          arrayStride: coloredProjection.arrayStride,
+          attributes: expect.arrayContaining([
+            { shaderLocation: 13, offset: 48, format: 'float32x4' },
+          ]),
+        },
+      ],
+    });
+  });
+
+  it('uses the same projection digest for PSO identity and variant selection', () => {
+    const plain = baseAttributes();
+    const colored = { ...plain, color: new Float32Array([1, 1, 1, 1]) };
+    const plainSpec = spec(plain);
+    const coloredSpec = spec(colored);
+    expect(cacheKeyOf(plainSpec)).not.toBe(cacheKeyOf(coloredSpec));
+    expect(
+      cacheKeyOf({
+        ...coloredSpec,
+        shader: { ...coloredSpec.shader, variantSet: 'VERTEX_COLOR_AVAILABLE=true' },
+      }),
+    ).not.toBe(cacheKeyOf(coloredSpec));
+  });
+
+  it('derives the default-unlit color axis from the mesh projection', () => {
+    const plain = deriveVertexLayoutProjection(baseAttributes());
+    const colored = deriveVertexLayoutProjection({
+      ...baseAttributes(),
+      color: new Float32Array([1, 0, 0, 1]),
+    });
+    expect(variantSetFromVertexLayoutProjection(plain, undefined)).toEqual({
+      ok: true,
+      value: 'VERTEX_COLOR_AVAILABLE=false',
+    });
+    expect(variantSetFromVertexLayoutProjection(colored, undefined)).toEqual({
+      ok: true,
+      value: 'VERTEX_COLOR_AVAILABLE=true',
+    });
+    const capabilityVariantSet = 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true';
+    expect(variantSetFromVertexLayoutProjection(plain, capabilityVariantSet)).toEqual({
+      ok: true,
+      value:
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+    });
+    expect(variantSetFromVertexLayoutProjection(colored, capabilityVariantSet)).toEqual({
+      ok: true,
+      value:
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=true',
+    });
+    expect(variantSetFromVertexLayoutProjection(colored, '')).toEqual({ ok: true, value: '' });
+    expect(variantSetFromVertexLayoutProjection(plain, '')).toEqual({
+      ok: true,
+      value: 'VERTEX_COLOR_AVAILABLE=false',
+    });
+  });
+
+  it('does not allocate color stream bytes for a plain mesh', () => {
+    const plain = packInterleavedVertexAttributes(baseAttributes(), 1);
+    expect(plain.ok).toBe(true);
+    if (!plain.ok) return;
+    expect(plain.value.projection.attributes.some((attribute) => attribute.key === 'color')).toBe(
+      false,
+    );
+    expect(plain.value.projection.arrayStride).toBe(48);
+    expect(plain.value.vertices.byteLength).toBe(48);
+  });
+
+  it('rejects an authored VERTEX_COLOR_AVAILABLE axis that disagrees with geometry', () => {
+    const plainProjection = deriveVertexLayoutProjection(baseAttributes());
+    const result = variantSetFromVertexLayoutProjection(
+      plainProjection,
+      'VERTEX_COLOR_AVAILABLE=true',
+    );
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('vertex-color-variant-conflict');
+    expect(result.error.detail).toMatchObject({
+      authored: true,
+      authoredValue: 'true',
+      projected: false,
+    });
+  });
+});

package/src/__tests__/vertex-layout-consumer.unit.test.ts

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const source = (name: string): string =>
+  readFileSync(new URL(`../${name}`, import.meta.url), 'utf8');
+
+describe('render consumes geometry layout projection', () => {
+  it('does not retain the legacy stride discriminator or uv count as layout authority', () => {
+    const renderData = source('render-data.ts');
+    const store = source('device/gpu-residency.ts');
+    const pipeline = source('pipeline-spec.ts');
+
+    expect(renderData).toMatch(/VertexLayoutProjection/);
+    expect(store).toMatch(/VertexLayoutProjection/);
+    expect(pipeline).toMatch(/VertexLayoutProjection/);
+    expect(renderData).toMatch(/deriveVertexLayoutProjection/);
+    expect(store).toMatch(/layoutProjection\.arrayStride/);
+  });
+
+  it('routes GPU layout construction through the geometry owner', () => {
+    const pipeline = source('pipeline-spec.ts');
+    expect(pipeline).toMatch(/deriveVertexLayoutProjection/);
+    expect(pipeline).not.toMatch(/function vertexLayoutDigest/);
+  });
+});

package/src/__tests__/visibility-diagnostics.integration.test.ts

@@ -0,0 +1,62 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { Camera } from '../components/camera';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { extractFrames } from '../render-system-extract';
+
+function spawnCamera(world: World): void {
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    )
+    .unwrap();
+}
+
+function spawnCandidate(world: World, state: keyof typeof VisibilityStateValue) {
+  return world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 200] } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Visibility, data: { state: VisibilityStateValue[state] } },
+    )
+    .unwrap();
+}
+
+describe('visibility diagnostics', () => {
+  it('switches from explicit hidden to frustum culling without changing frustum totals', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    spawnCamera(world);
+    const entity = spawnCandidate(world, 'hidden');
+    world.update(0).unwrap();
+
+    const hidden = extractFrames([world], 0);
+    expect(hidden.renderables).toHaveLength(0);
+    expect(hidden.visibilityStats).toEqual({ explicitlyHidden: 1 });
+    expect(hidden.frustumStats).toEqual({ culled: 0, total: 0 });
+
+    world.set(entity, Visibility, { state: VisibilityStateValue.visible }).unwrap();
+    const visible = extractFrames([world], 0);
+    expect(visible.renderables).toHaveLength(0);
+    expect(visible.visibilityStats).toEqual({ explicitlyHidden: 0 });
+    expect(visible.frustumStats).toEqual({ culled: 1, total: 1 });
+  });
+
+  it('sums hidden candidate sets per World without counting dispatches or submeshes', () => {
+    const first = new World();
+    const second = new World();
+    spawnCandidate(first, 'hidden');
+    spawnCandidate(second, 'hidden');
+
+    const frame = extractFrames([first, second], 0);
+
+    expect(frame.visibilityStats).toEqual({ explicitlyHidden: 2 });
+    expect(frame.dispatch).toHaveLength(0);
+  });
+});