@forgeax/engine-shader 0.1.27 → 0.1.29

package/src/__tests__/material-contract.unit.test.ts

@@ -2,9 +2,13 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { derive } from '@forgeax/engine-types';
 import Ajv2020 from 'ajv/dist/2020.js';
-import { describe, expect, it } from 'vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
 import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '../material-schemas.js';
 
+type EngineShaderManifest = Awaited<
+  ReturnType<typeof import('@forgeax/engine-vite-plugin-shader').buildEngineShaderManifest>
+>;
+
 const alphaSchema = JSON.parse(
   readFileSync(
     fileURLToPath(
@@ -59,6 +63,17 @@ describe('standard PBR material alpha contract', () => {
 });
 
 describe('standard PBR transmission material contract', () => {
+  // Manifest production is an integration boundary: compile the producer once
+  // and let each contract assertion consume the same receipt-backed result.
+  // Rebuilding it in every test made this unit file spend ~100s in CI and
+  // caused the 20s receipt assertion to time out without any semantic failure.
+  let engineManifest!: EngineShaderManifest;
+
+  beforeAll(async () => {
+    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+    engineManifest = await buildEngineShaderManifest();
+  }, 60_000);
+
   it('declares the seven transmission and volume parameters once, separate from CPU and GPU evidence', () => {
     const entries = DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter((entry) =>
       [
@@ -260,8 +275,7 @@ describe('standard PBR transmission material contract', () => {
       },
     ]);
 
-    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
-    const manifest = await buildEngineShaderManifest();
+    const manifest = engineManifest;
     const material = manifest.materialShaders.find(
       (entry) => entry.identifier === 'forgeax::default-standard-pbr',
     );
@@ -300,8 +314,7 @@ describe('standard PBR transmission material contract', () => {
     // timeout-only failure.
     timeout: 60_000,
   }, async () => {
-    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
-    const manifest = await buildEngineShaderManifest();
+    const manifest = engineManifest;
     const standard = manifest.materialShaders.find(
       (entry) => entry.identifier === 'forgeax::default-standard-pbr',
     );
@@ -324,8 +337,7 @@ describe('standard PBR transmission material contract', () => {
   it('composes the scene-index entry into the same validated PBR artifact as the direct entry', {
     timeout: 60_000,
   }, async () => {
-    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
-    const manifest = await buildEngineShaderManifest();
+    const manifest = engineManifest;
     const standard = manifest.materialShaders.find(
       (entry) => entry.identifier === 'forgeax::default-standard-pbr',
     );
@@ -338,11 +350,32 @@ describe('standard PBR transmission material contract', () => {
     expect(standard.reflection?.layoutIdentity).toBe(standard.receiptIdentity);
   });
 
+  it('keeps skin scene-index material rows and non-cluster punctual lighting in the GPU variant', {
+    timeout: 60_000,
+  }, async () => {
+    const manifest = engineManifest;
+    const skin = manifest.materialShaders.find((entry) => entry.identifier === 'forgeax::pbr-skin');
+    expect(skin).toBeDefined();
+    if (skin === undefined) return;
+    const sceneIndex = skin.variants.find(
+      (variant) =>
+        variant.defines.GPU_DRIVEN_SCENE_INDEX_AVAILABLE === true &&
+        variant.defines.STORAGE_BUFFER_AVAILABLE === true &&
+        variant.defines.CLUSTER_FORWARD_AVAILABLE === false &&
+        variant.defines.EXTENDED_LIGHTING_AVAILABLE === false &&
+        variant.defines.PROBE_BLEND_AVAILABLE === false &&
+        variant.defines.VERTEX_COLOR_AVAILABLE === false,
+    );
+    expect(sceneIndex).toBeDefined();
+    expect(sceneIndex?.composedWgsl).toContain('@binding(46)');
+    expect(sceneIndex?.composedWgsl).toMatch(/materialIndex/);
+    expect(sceneIndex?.composedWgsl).not.toMatch(/pointLightsBuffer|spotLightsBuffer/);
+  });
+
   it('rejects a receipt that loses a required prepared ABI field', {
     timeout: 60_000,
   }, async () => {
-    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
-    const manifest = await buildEngineShaderManifest();
+    const manifest = engineManifest;
     const standard = manifest.materialShaders.find(
       (entry) => entry.identifier === 'forgeax::default-standard-pbr',
     );

package/src/__tests__/material-derived-builtins.integration.test.ts

@@ -2,12 +2,16 @@ import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { derive } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '../material-schemas.js';
+import {
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  STANDARD_PBR_ARTIFACT_RECEIPT,
+  STANDARD_PBR_SKIN_ARTIFACT_RECEIPT,
+} from '../material-schemas.js';
 
 describe('material derived built-in integration contract', () => {
   it('routes every Standard lit consumer through the single Cluster accessor', () => {
     const sources = [
-      readFileSync(resolve(import.meta.dirname, '../default-standard-pbr.wgsl'), 'utf8'),
+      readFileSync(resolve(import.meta.dirname, '../standard-surface.wgsl'), 'utf8'),
       readFileSync(resolve(import.meta.dirname, '../default-standard-pbr-skin.wgsl'), 'utf8'),
     ];
 
@@ -37,6 +41,18 @@ describe('material derived built-in integration contract', () => {
     expect(skinned.totalBytes).toBe(standard.totalBytes);
   });
 
+  it('keeps direct and scene-index entries on one producer receipt', () => {
+    expect(STANDARD_PBR_ARTIFACT_RECEIPT.receiptIdentity).toBe(
+      STANDARD_PBR_SKIN_ARTIFACT_RECEIPT.receiptIdentity,
+    );
+    expect(STANDARD_PBR_ARTIFACT_RECEIPT.directEntry).toBe('vs_main');
+    expect(STANDARD_PBR_ARTIFACT_RECEIPT.sceneIndexEntry).toBe('vs_scene_index');
+    expect(STANDARD_PBR_SKIN_ARTIFACT_RECEIPT.skinPaletteAddress).toMatchObject({
+      group: 2,
+      binding: 1,
+    });
+  });
+
   it('includes a coordinate member pair for every built-in texture binding', () => {
     const derived = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
     const textureNames = DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter(

package/src/__tests__/probe-lighting-composition.unit.test.ts

@@ -4,7 +4,7 @@ import { describe, expect, it } from 'vitest';
 
 const shaderRoot = resolve(import.meta.dirname, '..');
 const probe = readFileSync(resolve(shaderRoot, 'lighting-probe.wgsl'), 'utf8');
-const standard = readFileSync(resolve(shaderRoot, 'default-standard-pbr.wgsl'), 'utf8');
+const standard = readFileSync(resolve(shaderRoot, 'standard-surface.wgsl'), 'utf8');
 const skin = readFileSync(resolve(shaderRoot, 'default-standard-pbr-skin.wgsl'), 'utf8');
 
 describe('Probe diffuse shader composition', () => {

package/src/__tests__/reflection-probe-sampling.unit.test.ts

@@ -6,6 +6,10 @@ const standardSource = readFileSync(
   new URL('../default-standard-pbr.wgsl', import.meta.url),
   'utf8',
 );
+const skinSource = readFileSync(
+  new URL('../default-standard-pbr-skin.wgsl', import.meta.url),
+  'utf8',
+);
 
 describe('Standard reflection probe sampling contract', () => {
   it('keeps global IBL helpers and adds a bounded local probe sampling helper', () => {
@@ -28,7 +32,7 @@ describe('Standard reflection probe sampling contract', () => {
     );
     expect(standardSource).toContain('kD * irradiance * diffuseAlbedo');
     expect(standardSource).toContain(
-      'output.reflectionFallback = vec4<f32>(reflectionFallback, 1.0);',
+      'output.reflectionFallback = vec4<f32>(reflectionFallback, standardSsrCoverage());',
     );
     expect(standardSource).not.toContain('output.reflectionFallback = vec4<f32>(ambient, 1.0);');
   });
@@ -40,6 +44,23 @@ describe('Standard reflection probe sampling contract', () => {
   });
 
   it('keeps zero-intensity probes distinguishable from an absent Skylight', () => {
-    expect(standardSource).toContain('max(-skylight.intensity - 1.0, 0.0) * ao');
+    expect(standardSource).toContain('decodeSpecularEnvironmentScale(');
+    expect(samplingSource).toContain('vec3<f32>(max(-intensity - 1.0, 0.0))');
+  });
+
+  it('keeps probe-blend and SSR on one sentinel-safe specular environment scale', () => {
+    // ReflectionProbe resources encode their intensity as a negative sentinel
+    // and use the Skylight color lanes for box metadata. Never multiply that
+    // metadata by the specular lobe. The same decoded scale must drive the
+    // PROBE_BLEND specular ambient term and detached SSR fallback.
+    expect(standardSource).toContain(
+      'let specularEnvironmentScale = decodeSpecularEnvironmentScale(',
+    );
+    expect(standardSource).toContain('specularIbl * specularEnvironmentScale');
+    expect(standardSource).toContain(
+      'reflectionFallback = reflectionFallback * specularEnvironmentScale * ao;',
+    );
+    expect(skinSource).toContain('let specularEnvironmentScale = decodeSpecularEnvironmentScale(');
+    expect(skinSource).toContain('specularIbl * specularEnvironmentScale');
   });
 });

package/src/__tests__/scene-temporal.unit.test.ts

@@ -10,6 +10,16 @@ const pbrTemporalConsumers = [
 ] as const;
 
 describe('scene temporal varyings', () => {
+  it.each([
+    ...localTemporalShaders,
+    ...pbrTemporalConsumers,
+  ])('%s shares main-depth raster coverage without jittering motion', (file) => {
+    const source = readFileSync(resolve(import.meta.dirname, '..', file), 'utf8');
+    expect(source).toContain('out.clip = view.worldViewProj * currentWorld;');
+    expect(source).toContain('out.currentClip = view.temporalCurrentViewProj * currentWorld;');
+    expect(source).not.toContain('out.clip = out.currentClip;');
+    expect(source.match(/@builtin\(position\) @invariant clip/g)).toHaveLength(2);
+  });
   it('defines the temporal-v1 accessor ABI in one owner module', () => {
     const source = readFileSync(resolve(import.meta.dirname, '..', 'scene-temporal.wgsl'), 'utf8');
     expect(source).toContain('struct SceneTemporalV1');

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

@@ -864,6 +864,7 @@ import {
         '#pragma variant_axis TRANSMISSION_AVAILABLE',
         '#pragma variant_axis DIRECTIONAL_PCSS_AVAILABLE',
         '#pragma variant_axis PROJECTOR_AVAILABLE',
+        '#pragma variant_axis GPU_DRIVEN_SCENE_INDEX_AVAILABLE',
         '#pragma variant_axis REFLECTION_FALLBACK_AVAILABLE',
       ]);
     });

package/src/__tests__/sprite-variants.unit.test.ts

@@ -122,6 +122,7 @@ describe('w6 (b) -- pbr / unlit / sprite-adjacent shaders DO NOT pick up PER_INS
       '#pragma variant_axis TRANSMISSION_AVAILABLE',
       '#pragma variant_axis DIRECTIONAL_PCSS_AVAILABLE',
       '#pragma variant_axis PROJECTOR_AVAILABLE',
+      '#pragma variant_axis GPU_DRIVEN_SCENE_INDEX_AVAILABLE',
       '#pragma variant_axis REFLECTION_FALLBACK_AVAILABLE',
     ]);
   });

package/src/__tests__/ssr-artifact.unit.test.ts

@@ -0,0 +1,141 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+interface ShaderBinding {
+  readonly binding: number;
+  readonly visibility: number;
+  readonly texture?: Readonly<Record<string, unknown>>;
+  readonly storageTexture?: Readonly<Record<string, unknown>>;
+}
+
+interface CompileValue {
+  readonly wgsl: string;
+  readonly glsl: string;
+  readonly bindings: readonly Readonly<Record<string, unknown>>[];
+  readonly manifestEntry: {
+    readonly hash: string;
+    readonly wgsl: string;
+    readonly glsl: string;
+    readonly bindings: string;
+  };
+  readonly deps: readonly string[];
+}
+
+interface CompileResult {
+  readonly ok: boolean;
+  readonly value?: CompileValue;
+  readonly error?: { readonly code: string; readonly message: string };
+}
+
+interface CompilerModule {
+  compileShader(
+    source: string,
+    options: { readonly id: string; readonly imports?: Readonly<Record<string, string>> },
+  ): Promise<CompileResult>;
+}
+
+const SHADER_PATHS = {
+  hiz: resolve(import.meta.dirname, '../ssr-hiz.wgsl'),
+  hizReduce: resolve(import.meta.dirname, '../ssr-hiz-reduce.wgsl'),
+  trace: resolve(import.meta.dirname, '../ssr-trace.wgsl'),
+  temporal: resolve(import.meta.dirname, '../ssr-temporal.wgsl'),
+  compose: resolve(import.meta.dirname, '../ssr-compose.wgsl'),
+} as const;
+
+const SOURCES = {
+  hiz: readFileSync(SHADER_PATHS.hiz, 'utf8'),
+  hizReduce: readFileSync(SHADER_PATHS.hizReduce, 'utf8'),
+  trace: readFileSync(SHADER_PATHS.trace, 'utf8'),
+  temporal: readFileSync(SHADER_PATHS.temporal, 'utf8'),
+  compose: readFileSync(SHADER_PATHS.compose, 'utf8'),
+} as const;
+const COMMON = readFileSync(resolve(import.meta.dirname, '../common.wgsl'), 'utf8');
+
+let compiler: CompilerModule;
+
+beforeAll(async () => {
+  compiler = (await import(
+    /* @vite-ignore */ new URL('../../../shader-compiler/dist/index.mjs', import.meta.url).href
+  )) as unknown as CompilerModule;
+});
+
+async function compile(name: keyof typeof SOURCES): Promise<CompileValue> {
+  const result = await compiler.compileShader(SOURCES[name], {
+    id: `forgeax_ssr::${name}`,
+    ...(name === 'trace' || name === 'hiz' || name === 'temporal' || name === 'compose'
+      ? { imports: { 'forgeax_view::common': COMMON } }
+      : {}),
+  });
+  expect(result.ok, result.ok ? undefined : `${name}: ${result.error?.message}`).toBe(true);
+  if (!result.ok || result.value === undefined) throw new Error(`failed to compile ${name}`);
+  return result.value;
+}
+
+describe('SSR built-in shader artifacts', () => {
+  it('owns one build-time source for each spatial producer stage', () => {
+    expect(SOURCES.hiz).toContain('#define_import_path forgeax_ssr::hiz');
+    expect(SOURCES.hizReduce).toContain('#define_import_path forgeax_ssr::hiz_reduce');
+    expect(SOURCES.trace).toContain('#define_import_path forgeax_ssr::trace');
+    expect(SOURCES.hiz).toContain('SSR_HIZ_FORMAT');
+    expect(SOURCES.hiz).toContain('linearizeSsrDepth');
+    expect(SOURCES.hiz).toContain('view.temporalProjection');
+    expect(SOURCES.hizReduce).toContain('reduceSsrHiZFootprint');
+    expect(SOURCES.trace).toContain('SSR_TRACE_MAX_COARSE_STEPS');
+    expect(SOURCES.trace).toContain('SSR_TRACE_MAX_REFINE_STEPS');
+    expect(SOURCES.trace).toContain('traceScreenRay');
+    expect(SOURCES.trace).toContain('textureLoad(hizPyramid');
+    expect(SOURCES.trace).toContain('view.ssrParams.w > 0.5');
+    expect(SOURCES.temporal).toContain('SsrTemporalParams');
+    expect(SOURCES.temporal).toContain('resolvedOutput');
+    expect(SOURCES.temporal).toContain('sourceSize.x == size.x * 2u');
+    expect(SOURCES.temporal).toContain('topLeft = textureLoad(currentTrace');
+    expect(SOURCES.temporal).toContain('bottomRight = textureLoad(currentTrace');
+    expect(SOURCES.temporal).toContain('count += 1.0');
+  });
+
+  it('compiles and reflects every artifact through the build-time compiler', async () => {
+    for (const name of Object.keys(SOURCES) as Array<keyof typeof SOURCES>) {
+      const value = await compile(name);
+      expect(value.wgsl.length).toBeGreaterThan(0);
+      if (name !== 'compose') expect(value.glsl).toBe('');
+      expect(value.manifestEntry.wgsl).toBe(value.wgsl);
+      if (name !== 'compose') expect(value.manifestEntry.glsl ?? '').toBe('');
+      expect(value.manifestEntry.hash).toMatch(/^[0-9a-f]{8,64}$/);
+      expect(value.deps).toEqual(name === 'hizReduce' ? [] : ['forgeax_view::common']);
+      expect(JSON.parse(value.manifestEntry.bindings)).toEqual(value.bindings);
+    }
+  });
+
+  it('keeps artifact identity content-addressed and deterministic', async () => {
+    for (const name of Object.keys(SOURCES) as Array<keyof typeof SOURCES>) {
+      const first = await compile(name);
+      const second = await compile(name);
+      expect(second.manifestEntry.hash).toBe(first.manifestEntry.hash);
+      expect(second.manifestEntry.wgsl).toBe(first.manifestEntry.wgsl);
+      expect(second.manifestEntry.bindings).toBe(first.manifestEntry.bindings);
+    }
+  });
+
+  it('keeps the runtime registry physically isolated from the compiler', () => {
+    const registrySource = readFileSync(
+      resolve(import.meta.dirname, '../ShaderRegistry.ts'),
+      'utf8',
+    );
+    const packageJson = JSON.parse(
+      readFileSync(resolve(import.meta.dirname, '../../package.json'), 'utf8'),
+    ) as { dependencies?: Record<string, string> };
+    expect(registrySource).not.toMatch(
+      /^\s*(?:import|export).*@forgeax\/engine-(?:shader-compiler|naga|wgpu-wasm)/mu,
+    );
+    expect(Object.keys(packageJson.dependencies ?? {})).not.toEqual(
+      expect.arrayContaining([
+        '@forgeax/engine-shader-compiler',
+        '@forgeax/engine-naga',
+        '@forgeax/engine-wgpu-wasm',
+      ]),
+    );
+  });
+});
+
+export type { ShaderBinding };

package/src/__tests__/ssr-bgl.integration.test.ts

@@ -0,0 +1,185 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { SSR_SHADER_MODULES } from '../index.js';
+
+interface CompileValue {
+  readonly bindings: readonly Readonly<Record<string, unknown>>[];
+  readonly manifestEntry: { readonly hash: string; readonly bindings: string };
+}
+
+interface CompileResult {
+  readonly ok: boolean;
+  readonly value?: CompileValue;
+  readonly error?: { readonly code: string; readonly message: string };
+}
+
+interface CompilerModule {
+  compileShader(
+    source: string,
+    options: { readonly id: string; readonly imports?: Readonly<Record<string, string>> },
+  ): Promise<CompileResult>;
+}
+
+const SOURCES = {
+  hiz: readFileSync(resolve(import.meta.dirname, '../ssr-hiz.wgsl'), 'utf8'),
+  hizReduce: readFileSync(resolve(import.meta.dirname, '../ssr-hiz-reduce.wgsl'), 'utf8'),
+  trace: readFileSync(resolve(import.meta.dirname, '../ssr-trace.wgsl'), 'utf8'),
+  temporal: readFileSync(resolve(import.meta.dirname, '../ssr-temporal.wgsl'), 'utf8'),
+} as const;
+const COMMON = readFileSync(resolve(import.meta.dirname, '../common.wgsl'), 'utf8');
+
+let compiler: CompilerModule;
+
+beforeAll(async () => {
+  compiler = (await import(
+    /* @vite-ignore */ new URL('../../../shader-compiler/dist/index.mjs', import.meta.url).href
+  )) as unknown as CompilerModule;
+});
+
+async function compile(name: keyof typeof SOURCES): Promise<CompileValue> {
+  const result = await compiler.compileShader(SOURCES[name], {
+    id: `forgeax_ssr::${name}`,
+    imports: { 'forgeax_view::common': COMMON },
+  });
+  expect(result.ok, result.ok ? undefined : result.error?.message).toBe(true);
+  if (!result.ok || result.value === undefined) throw new Error(`failed to compile ${name}`);
+  return result.value;
+}
+
+function entries(value: CompileValue): readonly Readonly<Record<string, unknown>>[] {
+  const group = value.bindings[0];
+  expect(group).toBeDefined();
+  if (group === undefined || !Array.isArray(group.entries)) throw new Error('missing group zero');
+  return group.entries as readonly Readonly<Record<string, unknown>>[];
+}
+
+function storageTexture(
+  entry: Readonly<Record<string, unknown>> | undefined,
+): Readonly<Record<string, unknown>> {
+  expect(entry?.storageTexture).toBeDefined();
+  if (
+    entry === undefined ||
+    typeof entry.storageTexture !== 'object' ||
+    entry.storageTexture === null
+  ) {
+    throw new Error('missing storage texture binding');
+  }
+  return entry.storageTexture as Readonly<Record<string, unknown>>;
+}
+
+describe('SSR built-in shader binding contract', () => {
+  it('reflects Hi-Z as a depth input plus r32float storage output', async () => {
+    const value = await compile('hiz');
+    const reflected = entries(value);
+    expect(reflected).toHaveLength(3);
+    expect(reflected[0]).toMatchObject({
+      binding: 0,
+      texture: { sampleType: 'depth', viewDimension: '2d' },
+    });
+    expect(storageTexture(reflected[1])).toMatchObject({
+      access: 'write-only',
+      format: 'r32float',
+      viewDimension: '2d',
+    });
+    expect(reflected[2]).toMatchObject({ binding: 2, buffer: { type: 'uniform' } });
+    expect(JSON.parse(value.manifestEntry.bindings)).toEqual(value.bindings);
+  });
+
+  it('reflects trace inputs including lighting-owned coverage and the shared View', async () => {
+    const value = await compile('trace');
+    const reflected = entries(value);
+    expect(reflected).toHaveLength(9);
+    for (let binding = 0; binding < 4; binding += 1) {
+      expect(reflected[binding]).toMatchObject({
+        binding,
+        texture: {
+          sampleType: binding === 0 ? 'depth' : 'unfilterable-float',
+          viewDimension: '2d',
+        },
+      });
+    }
+    expect(storageTexture(reflected[4])).toMatchObject({
+      access: 'write-only',
+      format: 'rgba16float',
+      viewDimension: '2d',
+    });
+    expect(reflected[5]).toMatchObject({ binding: 5, buffer: { type: 'uniform' } });
+    expect(reflected[7]).toMatchObject({
+      binding: 7,
+      texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+    });
+    expect(reflected[8]).toMatchObject({
+      binding: 8,
+      storageTexture: { access: 'write-only', format: 'r32float', viewDimension: '2d' },
+    });
+  });
+
+  it('reflects Hi-Z reduction as an r32float sampled input plus storage output', async () => {
+    const value = await compile('hizReduce');
+    const reflected = entries(value);
+    expect(reflected).toHaveLength(2);
+    expect(reflected[0]).toMatchObject({
+      binding: 0,
+      texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+    });
+    expect(storageTexture(reflected[1])).toMatchObject({
+      access: 'write-only',
+      format: 'r32float',
+      viewDimension: '2d',
+    });
+  });
+
+  it('reflects temporal resolve with packed actual normal and confidence history', async () => {
+    const value = await compile('temporal');
+    const reflected = entries(value);
+    expect(reflected).toHaveLength(12);
+    expect(reflected[11]).toMatchObject({
+      binding: 11,
+      texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+    });
+    expect(reflected[9]).toMatchObject({
+      binding: 9,
+      texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+    });
+    expect(reflected[10]).toMatchObject({
+      binding: 10,
+      storageTexture: { access: 'write-only', format: 'rgba8unorm', viewDimension: '2d' },
+    });
+    expect(reflected[8]).toMatchObject({ binding: 8, buffer: { type: 'uniform' } });
+    for (let binding = 0; binding < 5; binding += 1) {
+      expect(reflected[binding]).toMatchObject({
+        binding,
+        texture: {
+          sampleType: binding === 1 ? 'depth' : 'unfilterable-float',
+          viewDimension: '2d',
+        },
+      });
+    }
+    expect(storageTexture(reflected[5])).toMatchObject({
+      access: 'write-only',
+      format: 'rgba16float',
+      viewDimension: '2d',
+    });
+    expect(reflected[6]).toMatchObject({ binding: 6, buffer: { type: 'uniform' } });
+    expect(storageTexture(reflected[7])).toMatchObject({
+      access: 'write-only',
+      format: 'rgba16float',
+      viewDimension: '2d',
+    });
+  });
+
+  it('requires a registry-discoverable stable module id for each artifact', () => {
+    const registrySource = readFileSync(
+      resolve(import.meta.dirname, '../ShaderRegistry.ts'),
+      'utf8',
+    );
+    expect(registrySource).toContain('SSR_SHADER_MODULES');
+    expect(SSR_SHADER_MODULES).toEqual({
+      hiz: 'forgeax_ssr::hiz',
+      hizReduce: 'forgeax_ssr::hiz_reduce',
+      trace: 'forgeax_ssr::trace',
+      temporal: 'forgeax_ssr::temporal',
+    });
+  });
+});

package/src/__tests__/standard-output-domain.unit.test.ts

@@ -0,0 +1,36 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const shaderRoot = resolve(import.meta.dirname, '..');
+const outputEncoding = readFileSync(resolve(shaderRoot, 'output-encoding.wgsl'), 'utf8');
+const tonemap = readFileSync(resolve(shaderRoot, 'tonemap.wgsl'), 'utf8');
+
+describe('Standard output shader domain contract', () => {
+  it('owns the only explicit linear-LDR to display-sRGB conversion', () => {
+    expect(outputEncoding).toContain('linearToSrgbOetf');
+    expect(outputEncoding.match(/linearToSrgbOetf\s*\(/g)).toHaveLength(1);
+    expect(outputEncoding).toContain('fn encodeOutput');
+    expect(outputEncoding).toContain('return vec4<f32>(encoded, alpha);');
+    expect(tonemap).toContain('#import forgeax_view::output_encoding');
+    expect(tonemap).not.toContain('linearToSrgbOetf(mapped)');
+  });
+
+  it('keeps tone mapping in linear HDR to linear LDR and preserves alpha', () => {
+    expect(tonemap).toContain('fn toneMapLinearLdr');
+    expect(tonemap).toContain('fn mapTonemap');
+    expect(tonemap).toContain('fn fs_tone_only');
+    expect(tonemap).toContain('return vec4<f32>(mapTonemap(source.rgb), source.a);');
+    expect(tonemap).toContain('fn fs_encode_only');
+    expect(tonemap).toContain('return encodeFinal(source.rgb, source.a, in.position);');
+    expect(tonemap).not.toContain('encodedDestinationBlend');
+    expect(tonemap).toContain('ditherUnorm8(encoded.rgb, position.xy)');
+  });
+
+  it('fails closed when a route has no declared output encoding owner', () => {
+    const source = `${outputEncoding}\n${tonemap}`;
+    expect(source.match(/fn encodeOutput/g)).toHaveLength(1);
+    expect(source.match(/linearToSrgbOetf\s*\(/g)).toHaveLength(1);
+    expect(source).not.toMatch(/srgb.*attachment.*and.*explicit|explicit.*and.*srgb.*attachment/i);
+  });
+});