@forgeax/engine-render 0.1.2

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

@@ -0,0 +1,61 @@
+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('../hdrp-buffers.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../gpu-resource-store.ts', import.meta.url), 'utf8'),
+  readFileSync(new URL('../render-system.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'),
+  readFileSync(new URL('../renderer/renderer-factory.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('../hdrp-pipeline.ts', import.meta.url), 'utf8'),
+      readFileSync(new URL('../urp-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,389 @@
+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 { hdrpPipeline } from '../hdrp-pipeline';
+import type {
+  RenderPipeline,
+  RenderPipelineFrame,
+  RenderPipelineTopology,
+} from '../render-pipeline';
+import { createRenderPipelineTemporalContract } from '../render-pipeline';
+import { createRenderPipelineTarget } from '../render-pipeline-target';
+import { urpPipeline } from '../urp-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::urp' | 'forgeax::hdrp',
+  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 temporal = createRenderPipelineTemporalContract({
+    enabled: input.camera.antialias === 'taa',
+    rgba16floatRenderable: true,
+    maxColorAttachments: input.lane.maxColorAttachments,
+    project: (targets) => ok({ resolvedColor: targets.sceneColor }),
+  });
+  const built = pipeline.build(
+    {
+      graph,
+      projectGpuDriven: () => ok(undefined),
+      contributeFeatures: () => ok(undefined),
+      resolveTemporal: temporal.resolve,
+    },
+    input,
+  );
+  if (!built.ok) return built;
+  const finished = temporal.finish();
+  if (!finished.ok) return finished;
+  return graph.compile({
+    device,
+    surfaceSize: { width: input.surface.width, height: input.surface.height },
+  });
+}
+
+function projectTemporal(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  targets: Parameters<ReturnType<typeof createRenderPipelineTemporalContract>['resolve']>[0],
+) {
+  const output = createRenderPipelineTarget(graph, 'test-taa-resolved-color', {
+    format: 'rgba16float',
+    size: 'surface',
+  });
+  if (!output.ok) return output;
+  const pass = graph.addCopyPass('taa-resolve', {
+    accesses: [
+      { resource: targets.sceneColor.view, usage: 'copy-src' },
+      { resource: output.value.view, usage: 'copy-dst' },
+    ],
+    encode: () => undefined,
+  });
+  return pass.ok ? ok({ resolvedColor: { kind: 'scene-color' as const, ...output.value } }) : pass;
+}
+
+describe('typed built-in pipeline topology', () => {
+  it('orders HDRP compute, shadow, deferred, SSAO, forward, observation, and output work', () => {
+    const compiled = compile(
+      hdrpPipeline,
+      topology('forgeax::hdrp', {
+        config: { ssao: { enabled: 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(
+      hdrpPipeline,
+      topology('forgeax::hdrp', {
+        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(
+      urpPipeline,
+      topology('forgeax::urp', {
+        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-scratch-1']),
+    );
+  });
+
+  it('removes unsupported MSAA and composite post work on the fallback lane', () => {
+    const compiled = compile(
+      urpPipeline,
+      topology('forgeax::urp', {
+        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(
+      hdrpPipeline,
+      topology('forgeax::hdrp', {
+        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');
+  });
+
+  it.each([
+    ['forgeax::urp', urpPipeline],
+    ['forgeax::hdrp', hdrpPipeline],
+  ] as const)('calls the renderer temporal seam exactly once in %s', (pipelineId, pipeline) => {
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    let projected = 0;
+    const input = topology(pipelineId, {
+      camera: { tonemap: 'aces-filmic', antialias: 'taa', bloom: 'on' },
+    });
+    const temporal = createRenderPipelineTemporalContract({
+      enabled: true,
+      rgba16floatRenderable: true,
+      maxColorAttachments: 8,
+      project: (targets) => {
+        projected += 1;
+        return projectTemporal(graph, targets);
+      },
+    });
+    const built = pipeline.build(
+      {
+        graph,
+        projectGpuDriven: () => ok(undefined),
+        contributeFeatures: () => ok(undefined),
+        resolveTemporal: temporal.resolve,
+      },
+      input,
+    );
+    expect(built.ok).toBe(true);
+    expect(temporal.finish().ok).toBe(true);
+    expect(temporal.inspect()).toEqual({ resolveCount: 1 });
+    expect(projected).toBe(1);
+    const compiled = graph.compile({
+      device,
+      surfaceSize: { width: input.surface.width, height: input.surface.height },
+    });
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const names = compiled.value.inspect().passes.map((pass) => pass.name);
+    expect(names.filter((name) => name === 'scene-temporal')).toHaveLength(1);
+    expect(names.indexOf('scene-temporal')).toBeGreaterThan(
+      names.indexOf(pipelineId === 'forgeax::urp' ? 'main' : 'forward'),
+    );
+    expect(names.filter((name) => name === 'taa-resolve')).toHaveLength(1);
+    expect(names.indexOf('taa-resolve')).toBeGreaterThan(names.indexOf('scene-temporal'));
+    const temporalPass = compiled.value
+      .inspect()
+      .passes.find((pass) => pass.name === 'scene-temporal');
+    expect(temporalPass?.kind).toBe('raster');
+    expect(temporalPass?.accesses).toEqual(
+      expect.arrayContaining([
+        { resource: 'scene-temporal', usage: 'color-attachment' },
+        {
+          resource: 'scene-temporal-depth',
+          usage: 'depth-stencil-write',
+        },
+      ]),
+    );
+    expect(temporalPass?.accesses).not.toContainEqual({
+      resource: pipelineId === 'forgeax::urp' ? 'scene-depth' : 'hdrp-depth',
+      usage: 'depth-stencil-write',
+    });
+    expect(names.indexOf('linear-hdr-observation')).toBeGreaterThan(names.indexOf('taa-resolve'));
+    expect(names.indexOf('bloom-bright')).toBeGreaterThan(names.indexOf('taa-resolve'));
+    expect(names.indexOf('tonemap')).toBeGreaterThan(names.indexOf('taa-resolve'));
+    expect(names.indexOf('debug-overlay')).toBeGreaterThan(names.indexOf('tonemap'));
+  });
+
+  it('rejects custom TAA pipelines that omit or duplicate the resolve seam', () => {
+    const input = topology('forgeax::urp', {
+      camera: { tonemap: 'none', antialias: 'taa', bloom: 'off' },
+    });
+    const omitted = createRenderPipelineTemporalContract({
+      enabled: true,
+      rgba16floatRenderable: true,
+      maxColorAttachments: 8,
+      project: (targets) => ok({ resolvedColor: targets.sceneColor }),
+    });
+    const missing = omitted.finish();
+    expect(missing.ok).toBe(false);
+    if (!missing.ok) {
+      expect(missing.error.code).toBe('temporal-unsupported');
+      if (missing.error.code === 'temporal-unsupported') {
+        expect(missing.error.detail).toMatchObject({ reason: 'resolve-count' });
+      }
+    }
+
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const color = graph.createTexture('custom-color', { format: 'rgba16float', size: 'surface' });
+    const depth = graph.createTexture('custom-depth', { format: 'depth24plus', size: 'surface' });
+    const temporalTexture = graph.createTexture('custom-temporal', {
+      format: 'rgba16float',
+      size: 'surface',
+    });
+    expect(color.ok && depth.ok && temporalTexture.ok).toBe(true);
+    if (!color.ok || !depth.ok || !temporalTexture.ok) return;
+    const colorView = graph.view(color.value);
+    const depthView = graph.view(depth.value);
+    const temporalView = graph.view(temporalTexture.value);
+    expect(colorView.ok && depthView.ok && temporalView.ok).toBe(true);
+    if (!colorView.ok || !depthView.ok || !temporalView.ok) return;
+    const targets = {
+      sceneColor: {
+        kind: 'scene-color' as const,
+        texture: color.value,
+        view: colorView.value,
+        format: 'rgba16float',
+        sampleCount: 1 as const,
+      },
+      sceneDepth: {
+        kind: 'scene-depth' as const,
+        texture: depth.value,
+        view: depthView.value,
+        format: 'depth24plus',
+        sampleCount: 1 as const,
+      },
+      sceneTemporal: {
+        kind: 'scene-temporal' as const,
+        texture: temporalTexture.value,
+        view: temporalView.value,
+        format: 'rgba16float',
+        sampleCount: 1 as const,
+      },
+    };
+    const duplicate = createRenderPipelineTemporalContract({
+      enabled: input.camera.antialias === 'taa',
+      rgba16floatRenderable: true,
+      maxColorAttachments: 8,
+      project: (value) => ok({ resolvedColor: value.sceneColor }),
+    });
+    expect(duplicate.resolve(targets).ok).toBe(true);
+    const second = duplicate.resolve(targets);
+    expect(second.ok).toBe(false);
+    if (!second.ok) {
+      expect(second.error.code).toBe('temporal-unsupported');
+      if (second.error.code === 'temporal-unsupported') {
+        expect(second.error.detail).toMatchObject({ reason: 'resolve-count' });
+      }
+    }
+
+    const insufficient = createRenderPipelineTemporalContract({
+      enabled: true,
+      rgba16floatRenderable: false,
+      maxColorAttachments: 1,
+      project: (value) => ok({ resolvedColor: value.sceneColor }),
+    }).resolve(targets);
+    expect(insufficient.ok).toBe(false);
+    if (!insufficient.ok) expect(insufficient.error.code).toBe('taa-caps-insufficient');
+
+    const invalidDomain = createRenderPipelineTemporalContract({
+      enabled: true,
+      rgba16floatRenderable: true,
+      maxColorAttachments: 8,
+      project: (value) => ok({ resolvedColor: value.sceneColor }),
+    }).resolve({
+      ...targets,
+      sceneColor: { ...targets.sceneColor, format: 'bgra8unorm' },
+    });
+    expect(invalidDomain.ok).toBe(false);
+    if (!invalidDomain.ok) expect(invalidDomain.error.code).toBe('temporal-unsupported');
+  });
+});

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

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { resolveStandardRenderFeatureTargets } from '../features/targets';
+
+function targets(
+  tonemap: 'none' | 'aces-filmic',
+  antialias: 'none' | 'fxaa' | 'msaa' | 'taa',
+  storageBuffer: boolean,
+) {
+  return resolveStandardRenderFeatureTargets({
+    pipelineId: 'forgeax::urp',
+    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,
+    });
+  });
+
+  it('publishes packed temporal coverage only for TAA', () => {
+    expect(targets('none', 'taa', true)?.[2]).toMatchObject({
+      kind: 'scene-temporal',
+      format: 'rgba16float',
+      sampleCount: 1,
+    });
+    expect(targets('none', 'none', true)).toHaveLength(2);
+  });
+});

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

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { resolvePostColorDomainContract } from '../render-pipeline';
+
+describe('URP post color-domain order', () => {
+  it('declares the required linear-to-encoded stage sequence', () => {
+    expect(resolvePostColorDomainContract('urp')).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,124 @@
+import {
+  deriveVertexLayoutProjection,
+  packInterleavedVertexAttributes,
+} from '@forgeax/engine-geometry';
+import type { VertexAttributeMap } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { variantSetFromVertexLayoutProjection } from '../pipeline';
+import { buildPipelineDescriptor, cacheKeyOf, type PipelineSpec } 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: '' });
+  });
+
+  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('gpu-resource-store.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/);
+  });
+});