@forgeax/engine-shader 0.1.2

package/src/__tests__/sprite-lit-shader.test.ts

@@ -0,0 +1,240 @@
+// @forgeax/engine-shader / __tests__ / sprite-lit-shader.test.ts
+//
+// tweak-20260701-sprite-lit-flat-default-drop-ndotl-for-2d M1 / m1-1.
+//
+// Grep gates + fixture tests for the sprite-lit shader after the flat 2D
+// lighting fold: NdotL and Half-Lambert are removed, worldPos is emitted
+// from the vertex stage via VsOut interpolant.
+//
+// SSOTs:
+//   - plan-strategy D-P1 (VsOut carries `@location(1) worldPos`)
+//   - plan-strategy D-P2 (light functions drop normal parameter; flat SSOT)
+//   - requirements AC-05 (LoC net-down), AC-06 (no halfLambert/nDotL residue),
+//     AC-07 (typecheck + test:unit green)
+//   - research.md F-4 (LDR clamp / HDR pass-through)
+
+import { describe, expect, it } from 'vitest';
+import { createBuiltinMaterialAsset } from '../index.js';
+
+// Dynamic node:fs / node:module import via string ids — keeps the
+// engine-shader package free of static `import 'node:fs'` (which
+// shader.unit.test.ts already uses this pattern; see lines around the
+// fsId = 'node:fs' helper). The TS strict mode in this package's
+// tsconfig.lib does not ship @types/node by default; the dynamic-id
+// import avoids the missing type error.
+const fsId = 'node:fs';
+const moduleId = 'node:module';
+
+interface NodeFs {
+  readFileSync(path: string, encoding: string): string;
+  existsSync(path: string): boolean;
+}
+
+interface NodeModule {
+  createRequire(filename: string | URL): (id: string) => string;
+}
+
+async function loadFs(): Promise<NodeFs> {
+  const mod = (await import(fsId)) as NodeFs;
+  return mod;
+}
+async function loadModule(): Promise<NodeModule> {
+  const mod = (await import(moduleId)) as NodeModule;
+  return mod;
+}
+
+async function resolveSrcDir(): Promise<string> {
+  const m = await loadModule();
+  const require = m.createRequire(import.meta.url);
+  const packageJsonPath = require('@forgeax/engine-shader/package.json');
+  // require() returns the resolved JSON contents; we need the path, not
+  // the object. Fall back to require.resolve.
+  void packageJsonPath;
+  const resolved = m.createRequire(import.meta.url);
+  // Re-resolve by package.json path string.
+  const pkgJsonPath = (resolved as unknown as { resolve(id: string): string }).resolve(
+    '@forgeax/engine-shader/package.json',
+  );
+  return pkgJsonPath.replace(/package\.json$/, 'src');
+}
+
+async function readSpriteLitSource(): Promise<string> {
+  const fs = await loadFs();
+  const srcDir = await resolveSrcDir();
+  return fs.readFileSync(`${srcDir}/sprite-lit.wgsl`, 'utf8');
+}
+
+async function spriteLitWgslExists(): Promise<boolean> {
+  const fs = await loadFs();
+  const srcDir = await resolveSrcDir();
+  return fs.existsSync(`${srcDir}/sprite-lit.wgsl`);
+}
+
+describe('sprite-lit shader (flat 2D lighting, tweak-20260701 M1)', () => {
+  describe('sprite-lit.wgsl source artefact', () => {
+    it('file exists', async () => {
+      expect(await spriteLitWgslExists()).toBe(true);
+    });
+
+    it('first line is `#pragma variant_axis STORAGE_BUFFER_AVAILABLE`', async () => {
+      const src = await readSpriteLitSource();
+      const firstLine = src.split('\n')[0];
+      expect(firstLine).toBe('#pragma variant_axis STORAGE_BUFFER_AVAILABLE');
+    });
+
+    it('declares vs_main + fs_main + fs_main_hdr three entry points', async () => {
+      const src = await readSpriteLitSource();
+      expect(/@vertex[\s\S]*?fn vs_main\b/.test(src)).toBe(true);
+      expect(/@fragment[\s\S]*?fn fs_main\b/.test(src)).toBe(true);
+      expect(/@fragment[\s\S]*?fn fs_main_hdr\b/.test(src)).toBe(true);
+    });
+
+    it('does NOT reference normalTexture / normalSampler in fragment lighting code', async () => {
+      const src = await readSpriteLitSource();
+      expect(/textureSample\s*\(\s*normalTexture\b/.test(src)).toBe(false);
+      expect(/textureLoad\s*\(\s*normalTexture\b/.test(src)).toBe(false);
+    });
+
+    it('does NOT take a vertex normal attribute as a lighting input', async () => {
+      const src = await readSpriteLitSource();
+      expect(/dot\s*\(\s*in\.normal\b/.test(src)).toBe(false);
+      expect(/normalize\s*\(\s*in\.normal\b/.test(src)).toBe(false);
+    });
+
+    it('fs_main applies LDR clamp; fs_main_hdr does NOT clamp the output', async () => {
+      const src = await readSpriteLitSource();
+      const ldrIdx = src.indexOf('fn fs_main(');
+      const hdrIdx = src.indexOf('fn fs_main_hdr(');
+      expect(ldrIdx).toBeGreaterThan(0);
+      expect(hdrIdx).toBeGreaterThan(0);
+      const ldrBody = src.slice(ldrIdx, hdrIdx > ldrIdx ? hdrIdx : src.length);
+      const hdrBody = src.slice(hdrIdx);
+      const ldrClampToZeroOne =
+        /clamp\s*\([\s\S]+?,\s*(?:vec[234]<f32>\(\s*)?0\.0[\s\S]*?,\s*(?:vec[234]<f32>\(\s*)?1\.0/.test(
+          ldrBody,
+        );
+      expect(ldrClampToZeroOne).toBe(true);
+      const hdrVecClamp = /clamp\s*\(\s*vec[34]<f32>/.test(hdrBody);
+      const hdrVecBoundClamp = /clamp\s*\([^)]*,\s*vec[34]<f32>\(\s*0\.0/.test(hdrBody);
+      expect(hdrVecClamp).toBe(false);
+      expect(hdrVecBoundClamp).toBe(false);
+    });
+
+    it('imports lighting helpers via forgeax_pbr (no cascade shadow sampling)', async () => {
+      const src = await readSpriteLitSource();
+      expect(src.includes('_sampleShadowForCascade')).toBe(false);
+    });
+  });
+
+  describe('flat 2D lighting fold (AC-06 grep gate: no NdotL / Half-Lambert residue)', () => {
+    it('no `halfLambert` identifier anywhere in the shader', async () => {
+      const src = await readSpriteLitSource();
+      // Match the camelCase identifier only; documentation strings containing
+      // hyphenated "Half-Lambert" or unrelated words are not the target.
+      expect(/halfLambert/.test(src)).toBe(false);
+    });
+
+    it('no `nDotL` identifier anywhere in the shader', async () => {
+      const src = await readSpriteLitSource();
+      // Match the camelCase identifier only; hyphenated feature-id strings
+      // like "sprite-lit-...-ndotl-for-2d" or comments spelling "NdotL" are
+      // not the target -- only the WGSL variable name `nDotL`.
+      expect(/\bnDotL\b/.test(src)).toBe(false);
+    });
+
+    it('no `spriteLitNormal` function (flat shading has no hardcoded normal)', async () => {
+      const src = await readSpriteLitSource();
+      expect(src.includes('spriteLitNormal')).toBe(false);
+    });
+
+    it('no `spriteLitWorldPos` function (worldPos now comes from VsOut interpolant)', async () => {
+      const src = await readSpriteLitSource();
+      expect(src.includes('spriteLitWorldPos')).toBe(false);
+    });
+
+    it('no `dot(N` or `dot(normal` lighting term in the shader body', async () => {
+      const src = await readSpriteLitSource();
+      // Directional / point / spot lighting must not project onto any surface
+      // normal — flat shading treats the sprite as omnidirectional.
+      expect(/dot\s*\(\s*N\s*,/.test(src)).toBe(false);
+      expect(/dot\s*\(\s*normal\s*,/.test(src)).toBe(false);
+    });
+  });
+
+  describe('VsOut carries per-fragment worldPos (D-P1)', () => {
+    it('VsOut declares `@location(1) worldPos: vec3<f32>` interpolant', async () => {
+      const src = await readSpriteLitSource();
+      // Match the WGSL declaration inside the VsOut struct. Whitespace-tolerant.
+      const re = /@location\(\s*1\s*\)\s+worldPos\s*:\s*vec3<f32>/;
+      expect(re.test(src)).toBe(true);
+    });
+
+    it('vs_main writes `out.worldPos = world.xyz`', async () => {
+      const src = await readSpriteLitSource();
+      const re = /out\.worldPos\s*=\s*world\.xyz\s*;/;
+      expect(re.test(src)).toBe(true);
+    });
+
+    it('fs_main / fs_main_hdr consume `in.worldPos` (not a reconstructed local)', async () => {
+      const src = await readSpriteLitSource();
+      const consumers = src.match(/in\.worldPos/g) ?? [];
+      // At minimum: one consumer in each of fs_main and fs_main_hdr.
+      expect(consumers.length).toBeGreaterThanOrEqual(2);
+    });
+  });
+
+  describe('flat light functions drop normal parameter (D-P2)', () => {
+    it('spriteLitDirectional signature is `(albedo)` only', async () => {
+      const src = await readSpriteLitSource();
+      const re = /fn\s+spriteLitDirectional\s*\(\s*albedo\s*:\s*vec3<f32>\s*\)/;
+      expect(re.test(src)).toBe(true);
+    });
+
+    it('spriteLitPoint signature is `(p, worldPos, albedo)` — no normal', async () => {
+      const src = await readSpriteLitSource();
+      const re =
+        /fn\s+spriteLitPoint\s*\(\s*p\s*:\s*PointLight\s*,\s*worldPos\s*:\s*vec3<f32>\s*,\s*albedo\s*:\s*vec3<f32>\s*\)/;
+      expect(re.test(src)).toBe(true);
+    });
+
+    it('spriteLitSpot signature is `(s, worldPos, albedo)` — no normal', async () => {
+      const src = await readSpriteLitSource();
+      const re =
+        /fn\s+spriteLitSpot\s*\(\s*s\s*:\s*SpotLight\s*,\s*worldPos\s*:\s*vec3<f32>\s*,\s*albedo\s*:\s*vec3<f32>\s*\)/;
+      expect(re.test(src)).toBe(true);
+    });
+
+    it('spriteLitShadeAccum signature is `(albedo, worldPos)` — no normal', async () => {
+      const src = await readSpriteLitSource();
+      const re =
+        /fn\s+spriteLitShadeAccum\s*\(\s*albedo\s*:\s*vec3<f32>\s*,\s*worldPos\s*:\s*vec3<f32>\s*\)/;
+      expect(re.test(src)).toBe(true);
+    });
+  });
+
+  describe('sprite-lit authored material contract', () => {
+    it('uses the built-in source catalog instead of a sidecar schema', () => {
+      const material = createBuiltinMaterialAsset('sprite');
+      expect(material.passes?.[0]?.program.module).toBe('forgeax_material::sprite');
+      expect(material.values).toBeDefined();
+    });
+  });
+
+  describe('LDR / HDR clamp boundary fixture (numeric SSOT)', () => {
+    // Fixture: total lit accumulator = 5.0 across all lights.
+    // Expected LDR output (clamped) = 1.0; expected HDR output > 1.0.
+    // The TS port mirrors what the WGSL must do.
+    const fixtureLitAccumulated = 5.0;
+    const ldrOut = Math.min(1.0, fixtureLitAccumulated);
+    const hdrOut = fixtureLitAccumulated;
+
+    it('LDR output is clamped to 1.0 at intensity=5.0 fixture', () => {
+      expect(ldrOut).toBe(1.0);
+    });
+
+    it('HDR output passes through > 1.0 at intensity=5.0 fixture', () => {
+      expect(hdrOut > 1.0).toBe(true);
+      expect(hdrOut).toBeCloseTo(5.0, 5);
+    });
+  });
+});

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

@@ -0,0 +1,209 @@
+// sprite-variants.unit.test.ts -- feat-20260625-sprite-instances-and-tilemap-terrain-static-batch
+// M2 / w6 (red before w7).
+//
+// Structural test for the new PER_INSTANCE_REGION variant axis on sprite.wgsl.
+// Pre-w7 expectations (RED):
+//   sprite.wgsl declares ONE axis (STORAGE_BUFFER_AVAILABLE) -- the variant
+//   matrix is 2x1 = 2; assertion (a) below expects 2x2 = 4 and fails.
+// Post-w7 expectations (GREEN):
+//   sprite.wgsl declares TWO axes (STORAGE_BUFFER_AVAILABLE +
+//   PER_INSTANCE_REGION) for a 2x2 = 4 matrix; common.wgsl InstanceData
+//   gains an #if PER_INSTANCE_REGION == true conditional region field; the
+//   non-9-slice path in sprite.wgsl chooses its UV-region source via the
+//   same conditional, while the 9-slice path keeps reading material.region
+//   regardless (D-5; OOS-3 + 9-slice not in PER_INSTANCE_REGION scope).
+//
+// Reverse-falsifier assertions (b) lock the axis to sprite.wgsl alone -- if
+// somebody copies the #pragma into common.wgsl the cartesian product would
+// double pbr / unlit variant counts (D-4 explicitly rejected).
+//
+// Why structural / file-read rather than naga.parse: this package
+// physically isolates naga (4 grep gates) -- cross-module compile
+// validation lives in packages/runtime/src/__tests__/dawn/. Source-text
+// grep is the established idiom (ibl-modules-parse.test.ts;
+// register-material-shader.test.ts M1-w1 block).
+//
+// node:* are accessed via `await import(varId)` (vite-ignore) so the
+// shader tsconfig keeps `types: ["@webgpu/types"]` without pulling in
+// `@types/node` (the established cross-package pattern).
+//
+// Anchors:
+//   - requirements §AC-04 (4-variant cartesian matrix for sprite shading
+//     model under PER_INSTANCE_REGION x STORAGE_BUFFER_AVAILABLE)
+//   - plan-strategy §2 D-4 (axis declared only in sprite.wgsl, never in
+//     common.wgsl, so pbr/unlit do not pick up the new define)
+//   - plan-strategy §2 D-5 (9-slice path always reads material.region
+//     even when PER_INSTANCE_REGION=true; the instance-region field only
+//     drives the legacy single-quad path)
+//   - plan-strategy §4 R-2 / R-3 / R-6 (variant matrix isolation +
+//     useSlices compatibility + uniform-fallback safety)
+
+import { beforeAll, describe, expect, it } from 'vitest';
+
+interface NodeFs {
+  readFileSync: (p: string, enc: string) => string;
+}
+interface NodePath {
+  resolve: (...parts: string[]) => string;
+  dirname: (p: string) => string;
+}
+interface NodeUrl {
+  fileURLToPath: (u: string) => string;
+}
+
+let fs!: NodeFs;
+let srcDir!: string;
+
+beforeAll(async () => {
+  const fsId = 'node:fs';
+  const pathId = 'node:path';
+  const urlId = 'node:url';
+  fs = (await import(/* @vite-ignore */ fsId)) as NodeFs;
+  const path = (await import(/* @vite-ignore */ pathId)) as NodePath;
+  const url = (await import(/* @vite-ignore */ urlId)) as NodeUrl;
+  const here = url.fileURLToPath(import.meta.url);
+  srcDir = path.resolve(path.dirname(here), '..');
+});
+
+function readWgsl(file: string): string {
+  return fs.readFileSync(`${srcDir}/${file}`, 'utf8');
+}
+
+function stripComments(src: string): string {
+  return src
+    .split(/\r?\n/)
+    .map((line) => line.replace(/\/\/.*$/, ''))
+    .join('\n');
+}
+
+function variantAxes(src: string): readonly string[] {
+  const matches = stripComments(src).match(/#pragma\s+variant_axis\s+\w+/g) ?? [];
+  return matches;
+}
+
+describe('w6 (a) -- sprite.wgsl declares the PER_INSTANCE_REGION + STORAGE_BUFFER_AVAILABLE pair (AC-04)', () => {
+  it('sprite.wgsl carries exactly two #pragma variant_axis lines (2x2 = 4 cartesian variants)', () => {
+    const axes = variantAxes(readWgsl('sprite.wgsl'));
+    expect(axes).toHaveLength(2);
+    expect(axes).toContain('#pragma variant_axis STORAGE_BUFFER_AVAILABLE');
+    expect(axes).toContain('#pragma variant_axis PER_INSTANCE_REGION');
+  });
+});
+
+describe('w6 (b) -- pbr / unlit / sprite-adjacent shaders DO NOT pick up PER_INSTANCE_REGION (D-4 reverse falsifier)', () => {
+  // The reverse-falsifier guards plan-strategy D-4: if PER_INSTANCE_REGION
+  // is declared in common.wgsl the cartesian product would double the
+  // pbr / unlit variant count for zero runtime benefit. These assertions
+  // pin the axis to sprite.wgsl exclusively.
+  const NON_SPRITE_SHADERS = [
+    'common.wgsl',
+    'default-standard-pbr.wgsl',
+    'default-standard-pbr-skin.wgsl',
+    'unlit.wgsl',
+    'shadow_caster.wgsl',
+    'msdf-text.wgsl',
+  ] as const;
+
+  for (const file of NON_SPRITE_SHADERS) {
+    it(`${file} does NOT declare #pragma variant_axis PER_INSTANCE_REGION`, () => {
+      const src = readWgsl(file);
+      expect(src).not.toMatch(/#pragma\s+variant_axis\s+PER_INSTANCE_REGION/);
+    });
+  }
+
+  it('default-standard-pbr.wgsl keeps its storage, cluster, and vertex-color axes (none touch PER_INSTANCE_REGION)', () => {
+    const axes = variantAxes(readWgsl('default-standard-pbr.wgsl'));
+    expect(axes).toEqual([
+      '#pragma variant_axis STORAGE_BUFFER_AVAILABLE',
+      '#pragma variant_axis CLUSTER_FORWARD_AVAILABLE',
+      '#pragma variant_axis VERTEX_COLOR_AVAILABLE',
+    ]);
+  });
+
+  it('unlit.wgsl keeps its storage and vertex-color axes', () => {
+    const axes = variantAxes(readWgsl('unlit.wgsl'));
+    expect(axes).toEqual([
+      '#pragma variant_axis STORAGE_BUFFER_AVAILABLE',
+      '#pragma variant_axis VERTEX_COLOR_AVAILABLE',
+    ]);
+  });
+});
+
+describe('w6 (c) -- 9-slice path keeps reading material.region under PER_INSTANCE_REGION=true (D-5)', () => {
+  // OOS-3 + plan-strategy §2 D-5 lock 9-slice off the per-instance region
+  // path. The structural assertions encode that:
+  //   1. common.wgsl InstanceData carries the conditional region field so
+  //      the WGSL compiles for PER_INSTANCE_REGION=true x useSlices=true.
+  //   2. sprite.wgsl useSlices branch still references material.region
+  //      (not instances[idx].region) regardless of axis state.
+  //   3. The conditional that switches region sources lives ONLY inside
+  //      the non-9-slice branch -- the useSlices branch keeps a literal
+  //      `material.region` lookup (folded through region.zw / region.xy).
+
+  it('common.wgsl wraps the InstanceData region field in #if PER_INSTANCE_REGION == true', () => {
+    const src = readWgsl('common.wgsl');
+    // bug-20260610 SSOT (recorded in shader.unit.test.ts M1-w1): naga_oil's
+    // `#ifdef` only checks key presence, so the project standardised on
+    // `#if NAME == true` whenever a false branch is live. The new conditional
+    // follows the same idiom.
+    expect(src).toMatch(/#if\s+PER_INSTANCE_REGION\s*==\s*true[\s\S]*?region\s*:\s*vec4<f32>/);
+  });
+
+  it('common.wgsl InstanceData declares localFromInstance UNCONDITIONALLY (region is the only conditional field)', () => {
+    const src = readWgsl('common.wgsl');
+    // The struct still opens with localFromInstance regardless of axis state.
+    // The PER_INSTANCE_REGION conditional appends `region: vec4<f32>` after
+    // localFromInstance; it never wraps the base field.
+    expect(src).toMatch(
+      /struct\s+InstanceData\s*\{[^}]*localFromInstance\s*:\s*mat4x4<f32>[^}]*\}/s,
+    );
+  });
+
+  it('sprite.wgsl useSlices branch keeps reading material.region (D-5; not instances[idx].region)', () => {
+    const src = stripComments(readWgsl('sprite.wgsl'));
+    // Slice the useSlices block (`if (useSlices) { ... } else { ... }`) and
+    // assert it contains material.region but not instances[...].region.
+    const ifMatch = src.match(/if\s*\(\s*useSlices\s*\)\s*\{([\s\S]*?)\}\s*else\s*\{/);
+    expect(ifMatch, '9-slice branch (if (useSlices) { ... }) must be present').not.toBeNull();
+    const sliceBlock = ifMatch?.[1] ?? '';
+    expect(sliceBlock).toMatch(/material\.region/);
+    expect(sliceBlock).not.toMatch(/instances\s*\[[^\]]*\]\s*\.\s*region/);
+  });
+
+  it('sprite.wgsl non-9-slice branch switches region source via #if PER_INSTANCE_REGION == true', () => {
+    const src = readWgsl('sprite.wgsl');
+    // The else-branch (no slices) is the only place the conditional region
+    // source applies. Grep the file for the conditional + both legs --
+    // material.region (false leg) and instances[...].region (true leg).
+    expect(src).toMatch(/#if\s+PER_INSTANCE_REGION\s*==\s*true/);
+    // True leg must reference instances[idx].region (per-instance region).
+    expect(src).toMatch(/instances\s*\[[^\]]*\]\s*\.\s*region/);
+    // False leg must still reference material.region (default behaviour).
+    expect(src).toMatch(/material\.region/);
+  });
+});
+
+describe('w6 (d) -- MAX_UNIFORM_INSTANCES=128 stays unchanged under the new axis (R-6 uniform-fallback safety)', () => {
+  // Per research §Q-R-4.3 + plan-strategy §4 R-6:
+  //   stride = mat4 64 B + vec4 16 B = 80 B per instance
+  //   uniform-fallback worst case = 80 B x 128 = 10240 B
+  //   WebGL2 minimum UBO binding size = 16384 B
+  // 10240 < 16384 so the existing 128-cap survives. The shader-side
+  // expression of that contract is the literal `array<InstanceData, 128>`
+  // in common.wgsl's uniform fallback branch; this test pins the 128 there.
+
+  it('common.wgsl uniform-fallback declares array<InstanceData, 128> (unchanged from pre-feat)', () => {
+    const src = readWgsl('common.wgsl');
+    expect(src).toMatch(
+      /#if\s+STORAGE_BUFFER_AVAILABLE\s*==\s*true[\s\S]*?@group\(3\)[\s\S]*?#else[\s\S]*?@group\(3\)\s+@binding\(0\)\s+var<uniform>\s+instances\s*:\s*array<InstanceData,\s*128>/,
+    );
+  });
+
+  it('common.wgsl mentions MAX_UNIFORM_INSTANCES=128 doc anchor (charter F1 grep gate)', () => {
+    // The plan locks the cap at 128 even under the new 80 B stride
+    // (10240 B < 16384 B WebGL2 floor). Pin the doc anchor that explains
+    // why so a future drift attempt has to update the explanation too.
+    const src = readWgsl('common.wgsl');
+    expect(src).toMatch(/MAX_UNIFORM_INSTANCES\s*=\s*128/);
+  });
+});

package/src/__tests__/taa-resolve.unit.test.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const source = readFileSync(resolve(import.meta.dirname, '../taa-resolve.wgsl'), 'utf8');
+
+describe('taa-resolve.wgsl', () => {
+  it('keeps the fixed packed temporal and two-attachment ABI', () => {
+    expect(source).toContain('struct TaaResolveParams');
+    expect(source).toContain('@location(0) color');
+    expect(source).toContain('@location(1) temporal');
+    expect(source).toContain('output.temporal = temporal');
+    expect(source).toContain('current.a');
+  });
+
+  it('contains every v1 rejection and adaptive weighting term', () => {
+    expect(source).toContain('uv + params.currentJitterUv');
+    expect(source).toContain('in.uv - temporal.xy');
+    expect(source).toContain('closestCurrentTemporal(pixel, dimensions)');
+    expect(source).toContain('historyInBounds');
+    expect(source).toContain('depthDelta > depthThreshold');
+    expect(source).toContain('neighborhoodSquareMean');
+    expect(source).toContain('clamp(rgbToYCoCg(sampledHistory.rgb), clipMin, clipMax)');
+    expect(source).toContain('reactiveFactor');
+    expect(source).toContain('velocityFactor');
+    expect(source).toContain('depthFactor');
+    expect(source).toContain('lumaFactor');
+    expect(source).toContain('mix(0.88, 0.97, lumaFactor)');
+    expect(source).toContain('params.temporalFrameIndex < 8u');
+    expect(source).toContain('progressiveWeight');
+  });
+});

package/src/__tests__/transparent-pbr.unit.test.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const shader = readFileSync(resolve(import.meta.dirname, '../default-standard-pbr.wgsl'), 'utf8');
+
+describe('transparent PBR color domain contract', () => {
+  it('mixes transparent source and destination in the linear domain', () => {
+    expect(shader).toContain('blendLinearTransparent');
+    expect(shader).toContain('linearColorDomain');
+  });
+
+  it('does not contain a direct encoded-destination blend path', () => {
+    expect(shader).not.toContain('encodedDestinationBlend');
+  });
+
+  it('keeps HDR transparent output linear until the tone stage', () => {
+    expect(shader).toContain('linearHdrColorDomain');
+    expect(shader).toContain('toneStageInput');
+  });
+});

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

@@ -0,0 +1,52 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const SHADER_ROOT = new URL('../', import.meta.url);
+const SOURCES = [
+  'default-standard-pbr.wgsl',
+  'default-standard-pbr-skin.wgsl',
+  'unlit.wgsl',
+] as const;
+
+function source(file: (typeof SOURCES)[number]): string {
+  return readFileSync(new URL(file, SHADER_ROOT), 'utf8');
+}
+
+describe('M4 vertex-color shader contract', () => {
+  it.each(SOURCES)('%s declares the geometry-owned color variant axis', (file) => {
+    const text = source(file);
+    expect(text).toContain('#pragma variant_axis VERTEX_COLOR_AVAILABLE');
+    expect(text).toMatch(
+      /#ifdef\s+VERTEX_COLOR_AVAILABLE[\s\S]*?@location\(13\)\s+color\s*:\s*vec4<f32>/,
+    );
+    expect(text).toMatch(
+      /#ifdef\s+VERTEX_COLOR_AVAILABLE[\s\S]*?@location\(14\)\s+color\s*:\s*vec4<f32>/,
+    );
+    if (file !== 'unlit.wgsl') {
+      expect(text).toMatch(/@location\(13\)\s+uv7\s*:\s*vec2<f32>/);
+    }
+  });
+
+  it.each(
+    SOURCES,
+  )('%s has an explicit white false variant and does not add a material flag', (file) => {
+    const text = source(file);
+    expect(text).toMatch(/#else[\s\S]*?vec4<f32>\(1\.0\)/);
+    expect(text).not.toMatch(/hasColor|VERTEX_COLOR\s*:/);
+    expect(text).not.toMatch(/struct\s+Material\s*\{[^}]*\bcolor\b/s);
+  });
+
+  it.each(SOURCES)('%s applies vertex color to linear RGB and all alpha consumers', (file) => {
+    const text = source(file);
+    expect(text).toMatch(/baseColor\.rgb\s*\*\s*(?:baseSample|texSample)\.rgb\s*\*\s*\w+\.rgb/);
+    expect(text).toMatch(/baseColor\.a\s*\*\s*(?:baseSample|texSample)\.a\s*\*\s*\w+\.a/);
+    expect(text).toMatch(/alphaCutoff/);
+    expect(text).toMatch(/fs_temporal/);
+  });
+
+  it('keeps the existing inter-stage uv7 location while reserving color at 14', () => {
+    const text = source('default-standard-pbr.wgsl');
+    expect(text).toMatch(/@location\(13\)\s+uv7\s*:\s*vec2<f32>/);
+    expect(text).toMatch(/@location\(14\)\s+color\s*:\s*vec4<f32>/);
+  });
+});

package/src/atmosphere-background.wgsl

@@ -0,0 +1,80 @@
+#define_import_path forgeax_environment::background
+
+// @forgeax/engine-shader - atmosphere-background.wgsl
+//
+// Background composition is deliberately separate from the Preetham cube.
+// The sun disc is added exactly once at the background consumer and is never
+// part of the sky-cube or IBL producer output.
+
+#import forgeax_view::common::FullscreenOutput
+#import forgeax_view::common::View
+#import forgeax_view::common::fullscreen_triangle
+
+struct AtmosphereBackgroundParams {
+  sunDirection: vec3<f32>,
+  sunIlluminance: f32,
+  sunColor: vec3<f32>,
+  _sunColorPad: f32,
+  turbidity: f32,
+  rayleigh: f32,
+  mieCoefficient: f32,
+  mieDirectionalG: f32,
+  sunAngularRadius: f32,
+  sunDiscEnabled: f32,
+  _tailPad: vec2<f32>,
+};
+
+@group(0) @binding(0) var sky: texture_cube<f32>;
+@group(0) @binding(1) var skySampler: sampler;
+@group(0) @binding(2) var<uniform> view: View;
+@group(0) @binding(3) var<uniform> atmosphere: AtmosphereBackgroundParams;
+
+fn atmosphere_sun_disc_radiance(
+  viewDirection: vec3<f32>,
+  sunDirection: vec3<f32>,
+  sunColor: vec3<f32>,
+  sunIlluminance: f32,
+  angularRadius: f32,
+) -> vec3<f32> {
+  let alignment = dot(normalize(viewDirection), normalize(sunDirection));
+  let edge = smoothstep(
+    cos(max(angularRadius * 1.5, 1e-6)),
+    cos(max(angularRadius, 1e-6)),
+    alignment,
+  );
+  let solidAngle = 2.0 * 3.14159265359 * (1.0 - cos(max(angularRadius, 1e-6)));
+  return max(sunColor, vec3<f32>(0.0)) * max(sunIlluminance, 0.0) * edge / solidAngle;
+}
+
+@vertex
+fn atmosphere_background_vs(@builtin(vertex_index) vertexIndex: u32) -> FullscreenOutput {
+  // Keep the fullscreen primitive at the far plane. The render graph binds
+  // the existing depth authority read-only, so fixed-function less-equal
+  // rejects background fragments covered by geometry without sampling depth.
+  var output = fullscreen_triangle(vertexIndex);
+  output.position.z = 1.0;
+  return output;
+}
+
+fn atmosphere_background_direction(uv: vec2<f32>) -> vec3<f32> {
+  let ndc = vec4<f32>(uv.x * 2.0 - 1.0, 1.0 - uv.y * 2.0, 1.0, 1.0);
+  let world = view.inverseViewProj * ndc;
+  return normalize(world.xyz / world.w - view.cameraPos);
+}
+
+@fragment
+fn atmosphere_background_fs(input: FullscreenOutput) -> @location(0) vec4<f32> {
+  let direction = atmosphere_background_direction(input.uv);
+  let cubeDirection = vec3<f32>(direction.x, -direction.y, direction.z);
+  var radiance = textureSample(sky, skySampler, cubeDirection).rgb;
+  if (atmosphere.sunDiscEnabled > 0.5 && atmosphere.sunDirection.y > 0.0) {
+    radiance += atmosphere_sun_disc_radiance(
+      direction,
+      atmosphere.sunDirection,
+      atmosphere.sunColor,
+      atmosphere.sunIlluminance,
+      atmosphere.sunAngularRadius,
+    );
+  }
+  return vec4<f32>(radiance, 1.0);
+}