@forgeax/engine-shader 0.1.2

package/src/__tests__/atmosphere-preetham-numeric.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+
+type Vec3 = readonly [number, number, number];
+type PerezFits = readonly [
+  readonly [number, number],
+  readonly [number, number],
+  readonly [number, number],
+  readonly [number, number],
+  readonly [number, number],
+];
+
+const PAPER_FITS: Readonly<Record<'Y' | 'x' | 'y', PerezFits>> = {
+  Y: [
+    [0.1787, -1.463],
+    [-0.3554, 0.4275],
+    [-0.0227, 5.3251],
+    [0.1206, -2.5771],
+    [-0.067, 0.3703],
+  ],
+  x: [
+    [-0.0193, -0.2592],
+    [-0.0665, 0.0008],
+    [-0.0004, 0.2125],
+    [-0.0641, -0.8989],
+    [-0.0033, 0.0452],
+  ],
+  y: [
+    [-0.0167, -0.2608],
+    [-0.095, 0.0092],
+    [-0.0079, 0.2102],
+    [-0.0441, -1.6537],
+    [-0.0109, 0.0529],
+  ],
+};
+
+function normalize(value: Vec3): Vec3 {
+  const length = Math.hypot(...value);
+  return [value[0] / length, value[1] / length, value[2] / length];
+}
+
+function zenithYxy(sunTheta: number, turbidity: number): Vec3 {
+  const theta2 = sunTheta * sunTheta;
+  const theta3 = theta2 * sunTheta;
+  const turbidity2 = turbidity * turbidity;
+  const chi = (4 / 9 - turbidity / 120) * (Math.PI - 2 * sunTheta);
+  return [
+    (4.0453 * turbidity - 4.971) * Math.tan(chi) - 0.2155 * turbidity + 2.4192,
+    (0.00165 * theta3 - 0.00374 * theta2 + 0.00208 * sunTheta) * turbidity2 +
+      (-0.02902 * theta3 + 0.06377 * theta2 - 0.03202 * sunTheta + 0.00394) * turbidity +
+      (0.11693 * theta3 - 0.21196 * theta2 + 0.06052 * sunTheta + 0.25885),
+    (0.00275 * theta3 - 0.0061 * theta2 + 0.00316 * sunTheta) * turbidity2 +
+      (-0.04214 * theta3 + 0.0897 * theta2 - 0.04153 * sunTheta + 0.00515) * turbidity +
+      (0.15346 * theta3 - 0.26756 * theta2 + 0.06669 * sunTheta + 0.26688),
+  ];
+}
+
+function perez(theta: number, gamma: number, fits: PerezFits, turbidity: number): number {
+  const [a, b, c, d, e] = fits.map(([slope, intercept]) => slope * turbidity + intercept);
+  const safeCos = Math.max(Math.cos(theta), 0.01);
+  return Math.max(
+    (1 + (a ?? 0) * Math.exp((b ?? 0) / safeCos)) *
+      (1 + (c ?? 0) * Math.exp((d ?? 0) * gamma) + (e ?? 0) * Math.cos(gamma) ** 2),
+    1e-5,
+  );
+}
+
+function evaluatePaperYxy(viewInput: Vec3, sunInput: Vec3, turbidity: number): Vec3 {
+  const view = normalize([viewInput[0], Math.max(viewInput[1], 0), viewInput[2]]);
+  const sun = normalize(sunInput);
+  const theta = Math.acos(Math.max(0, Math.min(1, view[1])));
+  const sunTheta = Math.acos(Math.max(0, Math.min(1, sun[1])));
+  const gamma = Math.acos(
+    Math.max(-1, Math.min(1, view[0] * sun[0] + view[1] * sun[1] + view[2] * sun[2])),
+  );
+  const zenith = zenithYxy(sunTheta, turbidity);
+  return (['Y', 'x', 'y'] as const).map((channel, index) => {
+    const relative =
+      perez(theta, gamma, PAPER_FITS[channel], turbidity) /
+      perez(0, sunTheta, PAPER_FITS[channel], turbidity);
+    return (zenith[index] ?? 0) * relative;
+  }) as unknown as Vec3;
+}
+
+function yxyToLinearSrgb([Y, x, y]: Vec3): Vec3 {
+  const safeY = Math.max(y, 1e-5);
+  const X = (Y * x) / safeY;
+  const Z = (Y * Math.max(1 - x - y, 0)) / safeY;
+  return [
+    3.2406 * X - 1.5372 * Y - 0.4986 * Z,
+    -0.9689 * X + 1.8758 * Y + 0.0415 * Z,
+    0.0557 * X - 0.204 * Y + 1.057 * Z,
+  ].map((channel) => Math.min(Math.max(channel, 0), 65504)) as unknown as Vec3;
+}
+
+describe('Preetham 1999 independent numeric oracle', () => {
+  it.each([
+    ['morning zenith', [0, 1, 0], [-0.45, 0.22, -0.865], 3.2, [3.225319, 0.260094, 0.274286]],
+    [
+      'morning horizon',
+      [0.1, 0, -0.995],
+      [-0.45, 0.22, -0.865],
+      3.2,
+      [11.048136, 0.378332, 0.377748],
+    ],
+    ['noon zenith', [0, 1, 0], [0.1, 0.97, -0.22], 2.1, [9.491382, 0.263007, 0.270884]],
+    [
+      'evening circumsolar',
+      [0.5, 0.15, -0.85],
+      [0.5, 0.15, -0.85],
+      4.2,
+      [19.689314, 0.412721, 0.425093],
+    ],
+  ] as const)('%s matches the pinned Y/x/y reference', (_name, view, sun, turbidity, expected) => {
+    const actual = evaluatePaperYxy(view, sun, turbidity);
+    expect(actual[0]).toBeCloseTo(expected[0], 5);
+    expect(actual[1]).toBeCloseTo(expected[1], 5);
+    expect(actual[2]).toBeCloseTo(expected[2], 5);
+    expect(
+      yxyToLinearSrgb(actual).every((channel) => Number.isFinite(channel) && channel <= 65504),
+    ).toBe(true);
+  });
+});

package/src/__tests__/atmosphere-preetham-red.test.ts

@@ -0,0 +1,52 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+interface NodeFs {
+  existsSync(path: string): boolean;
+  readFileSync(path: string, encoding: string): string;
+}
+
+interface NodePath {
+  dirname(path: string): string;
+  resolve(...parts: string[]): string;
+}
+
+interface NodeUrl {
+  fileURLToPath(url: string): string;
+}
+
+let source = '';
+
+beforeAll(async () => {
+  const fs = (await import(/* @vite-ignore */ 'node:fs')) as unknown as NodeFs;
+  const path = (await import(/* @vite-ignore */ 'node:path')) as unknown as NodePath;
+  const url = (await import(/* @vite-ignore */ 'node:url')) as unknown as NodeUrl;
+  const shaderPath = path.resolve(
+    path.dirname(url.fileURLToPath(import.meta.url)),
+    '..',
+    'atmosphere-preetham.wgsl',
+  );
+  expect(fs.existsSync(shaderPath)).toBe(true);
+  source = fs.readFileSync(shaderPath, 'utf8');
+});
+
+describe('Preetham artifact contract (red gate)', () => {
+  it('pins one algorithm revision and independent Y/x/y coefficient tables', () => {
+    expect(source).toContain('PREETHAM_ALGORITHM_REVISION');
+    expect(source).toContain('PREETHAM_PEREZ_Y_COEFFICIENTS');
+    expect(source).toContain('PREETHAM_PEREZ_X_COEFFICIENTS');
+    expect(source).toContain('PREETHAM_PEREZ_SMALL_Y_COEFFICIENTS');
+    expect(source).toContain('1999');
+  });
+
+  it('owns Yxy to linear-sRGB conversion and below-horizon clamp', () => {
+    expect(source).toContain('preetham_yxy_to_linear_srgb');
+    expect(source).toContain('preetham_sky_radiance');
+    expect(source).toMatch(/max\([^\n]*\.y[^\n]*0\.0/);
+    expect(source).toContain('finite');
+  });
+
+  it('does not create a second evaluator or inject a disc into the cube', () => {
+    expect(source.match(/fn\s+preetham_sky_radiance\b/g) ?? []).toHaveLength(1);
+    expect(source).not.toContain('sun_disc');
+  });
+});

package/src/__tests__/atmosphere-preetham.test.ts

@@ -0,0 +1,132 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+interface NodeFs {
+  readFileSync(path: string, encoding: string): string;
+}
+
+interface NodePath {
+  dirname(path: string): string;
+  resolve(...parts: string[]): string;
+}
+
+interface NodeUrl {
+  fileURLToPath(url: string): string;
+}
+
+interface CompilerModule {
+  compileShader(
+    source: string,
+    options: {
+      readonly id: string;
+      readonly imports?: Readonly<Record<string, string>>;
+    },
+  ): Promise<{ readonly ok: boolean; readonly error?: { readonly code: string } }>;
+}
+
+let source = '';
+let producerSource = '';
+
+beforeAll(async () => {
+  const fs = (await import(/* @vite-ignore */ 'node:fs')) as unknown as NodeFs;
+  const path = (await import(/* @vite-ignore */ 'node:path')) as unknown as NodePath;
+  const url = (await import(/* @vite-ignore */ 'node:url')) as unknown as NodeUrl;
+  source = fs.readFileSync(
+    path.resolve(
+      path.dirname(url.fileURLToPath(import.meta.url)),
+      '..',
+      'atmosphere-preetham.wgsl',
+    ),
+    'utf8',
+  );
+  producerSource = fs.readFileSync(
+    path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..', 'atmosphere-cubemap.wgsl'),
+    'utf8',
+  );
+});
+
+function finite(value: number): boolean {
+  return Number.isFinite(value) && value >= 0;
+}
+
+function yxyToLinearSrgb(Y: number, x: number, y: number): [number, number, number] {
+  const safeY = Math.max(y, 1e-5);
+  const X = (Y * x) / safeY;
+  const Z = (Y * Math.max(1 - x - y, 0)) / safeY;
+  return [
+    Math.max(3.2406 * X - 1.5372 * Y - 0.4986 * Z, 0),
+    Math.max(-0.9689 * X + 1.8758 * Y + 0.0415 * Z, 0),
+    Math.max(0.0557 * X - 0.204 * Y + 1.057 * Z, 0),
+  ].map((channel) => Math.min(channel, 65504)) as [number, number, number];
+}
+
+describe('Preetham analytic sky artifact', () => {
+  it('is one pinned build-time evaluator with a separate background disc', () => {
+    expect(source.match(/fn\s+preetham_sky_radiance\b/g) ?? []).toHaveLength(1);
+    expect(source).toContain('PREETHAM_ALGORITHM_REVISION');
+    expect(source).toContain('PREETHAM_PEREZ_Y_COEFFICIENTS');
+    expect(source).toContain('PREETHAM_PEREZ_X_COEFFICIENTS');
+    expect(source).toContain('PREETHAM_PEREZ_SMALL_Y_COEFFICIENTS');
+    expect(source).not.toContain('const PREETHAM_PEREZ_COEFFICIENTS');
+    expect(source).toContain('preetham_zenith_yxy');
+    expect(source).toContain('preetham_relative_perez');
+    expect(source).toContain('preetham_yxy_to_linear_srgb');
+    expect(source).toContain('preetham_finite_guard');
+    expect(source).toContain('let daylightWeight = smoothstep(-0.12, 0.02, sun.y)');
+  });
+
+  it('keeps the Y/x/y component order and luminance in the XYZ conversion', () => {
+    expect(source).toMatch(/let\s+Y\s*=\s*max\(yxy\.x/);
+    expect(source).toMatch(/let\s+x\s*=\s*clamp\(yxy\.y/);
+    expect(source).toMatch(/let\s+y\s*=\s*clamp\(yxy\.z/);
+    expect(yxyToLinearSrgb(1, 1 / 3, 1 / 3)).toEqual(
+      expect.arrayContaining([
+        expect.closeTo(1.2048, 4),
+        expect.closeTo(0.9484, 4),
+        expect.closeTo(0.9087, 4),
+      ]),
+    );
+    const low = yxyToLinearSrgb(0.5, 0.28, 0.3);
+    const high = yxyToLinearSrgb(1, 0.28, 0.3);
+    expect(high[0] / low[0]).toBeCloseTo(2, 5);
+    expect(high[1] / low[1]).toBeCloseTo(2, 5);
+    expect(high[2] / low[2]).toBeCloseTo(2, 5);
+  });
+
+  it('passes the build-time Naga validation path', async () => {
+    const compiler = (await import(
+      /* @vite-ignore */ new URL('../../../shader-compiler/dist/index.mjs', import.meta.url).href
+    )) as unknown as CompilerModule;
+    const result = await compiler.compileShader(source, {
+      id: 'forgeax_environment::preetham',
+    });
+    expect(result.ok).toBe(true);
+  });
+
+  it('validates the sole cubemap producer caller through composition', async () => {
+    const compiler = (await import(
+      /* @vite-ignore */ new URL('../../../shader-compiler/dist/index.mjs', import.meta.url).href
+    )) as unknown as CompilerModule;
+    const result = await compiler.compileShader(producerSource, {
+      id: 'forgeax_environment::cubemap',
+      imports: { 'forgeax_environment::preetham': source },
+    });
+    expect(result.ok).toBe(true);
+    expect(producerSource.match(/preetham_sky_radiance\s*\(/g) ?? []).toHaveLength(1);
+    expect(producerSource).not.toMatch(/-input\.direction\.y/);
+  });
+
+  it.each([
+    ['horizon', 4.2, 0.3, 0.32],
+    ['zenith', 2.1, 0.25, 0.27],
+    ['extreme-low-lux', 0, 0.25, 0.27],
+  ])('%s Yxy probe remains finite', (_name, Y, x, y) => {
+    expect(yxyToLinearSrgb(Y, x, y).every(finite)).toBe(true);
+  });
+
+  it('scales sky radiance with illuminance without changing direct-light ownership', () => {
+    const low = yxyToLinearSrgb(2, 0.28, 0.3);
+    const high = yxyToLinearSrgb(4, 0.28, 0.3);
+    expect(high[1] / low[1]).toBeCloseTo(2, 5);
+    expect(source).not.toContain('sun_disc');
+  });
+});

package/src/__tests__/atmosphere-three-r184-reference.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+
+type Vec3 = readonly [number, number, number];
+
+const THREE_R184_SOURCE = 'three.js@r184/examples/jsm/objects/Sky.js';
+const RAYLEIGH = 1.1;
+const MIE_COEFFICIENT = 0.006;
+const MIE_DIRECTIONAL_G = 0.78;
+const TOTAL_RAYLEIGH: Vec3 = [5.804542996261093e-6, 1.3562911419845635e-5, 3.0265902468824876e-5];
+const MIE_CONST: Vec3 = [1.8399918514433978e14, 2.7798023919660528e14, 4.0790479543861094e14];
+
+const PROFILES = {
+  morning: { sun: [-0.45, 0.22, -0.865] as Vec3, turbidity: 3.2 },
+  noon: { sun: [0.1, 0.97, -0.22] as Vec3, turbidity: 2.1 },
+  evening: { sun: [0.5, 0.15, -0.85] as Vec3, turbidity: 4.2 },
+} as const;
+
+function normalize(value: Vec3): Vec3 {
+  const length = Math.hypot(...value);
+  return [value[0] / length, value[1] / length, value[2] / length];
+}
+
+function dot(left: Vec3, right: Vec3): number {
+  return left[0] * right[0] + left[1] * right[1] + left[2] * right[2];
+}
+
+function threeR184Sky(
+  directionInput: Vec3,
+  sunInput: Vec3,
+  turbidity: number,
+  showSunDisc: boolean,
+): Vec3 {
+  const direction = normalize(directionInput);
+  const sun = normalize(sunInput);
+  const sunZenithCos = Math.max(-1, Math.min(1, sun[1]));
+  const sunEnergy =
+    1000 * Math.max(0, 1 - Math.exp(-((1.6110731556870734 - Math.acos(sunZenithCos)) / 1.5)));
+  const sunFade = 1 - Math.max(0, Math.min(1, 1 - Math.exp(sun[1] / 450_000)));
+  const rayleighCoefficient = RAYLEIGH - (1 - sunFade);
+  const betaR = TOTAL_RAYLEIGH.map((value) => value * rayleighCoefficient) as unknown as Vec3;
+  // biome-ignore lint/suspicious/noApproximativeNumericConstant: Three r184 pins 0.434 exactly.
+  const mieScale = 0.434 * (0.2 * turbidity * 1e-17) * MIE_COEFFICIENT;
+  const betaM = MIE_CONST.map((value) => value * mieScale) as unknown as Vec3;
+  const zenithAngle = Math.acos(Math.max(0, direction[1]));
+  const inverse =
+    1 / (Math.cos(zenithAngle) + 0.15 * (93.885 - (zenithAngle * 180) / Math.PI) ** -1.253);
+  const sR = 8_400 * inverse;
+  const sM = 1_250 * inverse;
+  const cosTheta = dot(direction, sun);
+  const rayleighPhase = 0.05968310365946075 * (1 + (cosTheta * 0.5 + 0.5) ** 2);
+  const g2 = MIE_DIRECTIONAL_G ** 2;
+  const miePhase =
+    0.07957747154594767 * ((1 - g2) / (1 - 2 * MIE_DIRECTIONAL_G * cosTheta + g2) ** 1.5);
+  const lowSunMix = Math.max(0, Math.min(1, (1 - sun[1]) ** 5));
+  const colorOffset: Vec3 = [0, 0.0003, 0.00075];
+
+  return ([0, 1, 2] as const).map((channel) => {
+    const extinction = Math.exp(-(betaR[channel] * sR + betaM[channel] * sM));
+    const scatter =
+      sunEnergy *
+      ((betaR[channel] * rayleighPhase + betaM[channel] * miePhase) /
+        (betaR[channel] + betaM[channel]));
+    let lin = Math.max(scatter * (1 - extinction), 0) ** 1.5;
+    lin *= 1 - lowSunMix + lowSunMix * Math.max(scatter * extinction, 0) ** 0.5;
+    const disc =
+      showSunDisc && cosTheta >= 0.9999566769464484 ? sunEnergy * 19_000 * extinction : 0;
+    return (lin + 0.1 * extinction + disc) * 0.04 + colorOffset[channel];
+  }) as unknown as Vec3;
+}
+
+describe('Three.js r184 same-parameter model reference', () => {
+  it('pins natural daylight probes independently from the ForgeaX evaluator', () => {
+    const probes = Object.entries(PROFILES).map(([time, profile]) => {
+      const horizon = normalize([profile.sun[0], 0.08, profile.sun[2]]);
+      return {
+        time,
+        zenith: threeR184Sky([0, 1, 0], profile.sun, profile.turbidity, false),
+        horizon: threeR184Sky(horizon, profile.sun, profile.turbidity, false),
+      };
+    });
+    const expected = [
+      {
+        time: 'morning',
+        zenith: [0.030492, 0.102424, 0.308226],
+        horizon: [45.588088, 44.78799, 25.700271],
+      },
+      {
+        time: 'noon',
+        zenith: [1.520243, 3.631492, 7.981302],
+        horizon: [0.917458, 2.878871, 7.094558],
+      },
+      {
+        time: 'evening',
+        zenith: [0.019634, 0.063679, 0.19124],
+        horizon: [81.28711, 73.286304, 34.37594],
+      },
+    ] as const;
+    expect(THREE_R184_SOURCE).toBe('three.js@r184/examples/jsm/objects/Sky.js');
+    for (const [index, probe] of probes.entries()) {
+      const fixture = expected[index];
+      expect(probe.time).toBe(fixture?.time);
+      for (const channel of [0, 1, 2] as const) {
+        expect(probe.zenith[channel]).toBeCloseTo(fixture?.zenith[channel] ?? Number.NaN, 5);
+        expect(probe.horizon[channel]).toBeCloseTo(fixture?.horizon[channel] ?? Number.NaN, 5);
+      }
+    }
+    expect(probes[0]?.horizon[0]).toBeGreaterThan(
+      probes[0]?.horizon[2] ?? Number.POSITIVE_INFINITY,
+    );
+    expect(probes[1]?.zenith[2]).toBeGreaterThan(probes[1]?.zenith[0] ?? Number.POSITIVE_INFINITY);
+    expect(probes[2]?.horizon[0]).toBeGreaterThan(
+      probes[2]?.horizon[2] ?? Number.POSITIVE_INFINITY,
+    );
+  });
+
+  it('keeps the display Sun separable from the environment reference', () => {
+    const profile = PROFILES.morning;
+    const hidden = threeR184Sky(profile.sun, profile.sun, profile.turbidity, false);
+    const visible = threeR184Sky(profile.sun, profile.sun, profile.turbidity, true);
+    expect(visible[0]).toBeGreaterThan(hidden[0] * 100);
+  });
+});

package/src/__tests__/bloom-fxaa-tonemap.unit.test.ts

@@ -0,0 +1,31 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const shaderRoot = resolve(import.meta.dirname, '..');
+const tonemap = readFileSync(resolve(shaderRoot, 'tonemap.wgsl'), 'utf8');
+const bloom = readFileSync(resolve(shaderRoot, 'bloom-blur.wgsl'), 'utf8');
+const fxaa = readFileSync(resolve(shaderRoot, 'fxaa.wgsl'), 'utf8');
+
+describe('post shader color-domain contract', () => {
+  it('marks tone as the only HDR-to-LDR transition', () => {
+    expect(tonemap).toContain('linearHdrColorDomain');
+    expect(tonemap).toContain('linearLdrColorDomain');
+  });
+
+  it('keeps bloom and FXAA in linear domains', () => {
+    expect(bloom).toContain('linearHdrColorDomain');
+    expect(fxaa).toContain('linearLdrColorDomain');
+    expect(fxaa).toContain('linearToSrgbOetf');
+  });
+
+  it('does not blend into an encoded destination', () => {
+    expect(`${tonemap}\n${bloom}\n${fxaa}`).not.toContain('encodedDestinationBlend');
+  });
+
+  it('preserves source alpha through the output pass', () => {
+    expect(tonemap).toContain('let source = textureSample(hdr, samp, in.uv);');
+    expect(tonemap).toContain('return vec4<f32>(mapped, source.a);');
+    expect(tonemap).not.toContain('return vec4<f32>(mapped, 1.0);');
+  });
+});

package/src/__tests__/builtin-texture-sampling-contract.test.ts

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const shaderFiles = [
+  'default-standard-pbr.wgsl',
+  'default-standard-pbr-skin.wgsl',
+  'unlit.wgsl',
+  'sprite.wgsl',
+  'sprite-lit.wgsl',
+  'msdf-text.wgsl',
+] as const;
+
+function source(file: string): string {
+  return readFileSync(fileURLToPath(new URL(`../${file}`, import.meta.url)), 'utf8');
+}
+
+describe('built-in texture coordinate records', () => {
+  it('does not declare hand-written texture coordinate members', () => {
+    for (const file of shaderFiles) {
+      const text = source(file);
+      expect(text, `${file} has fixed UV scale members`).not.toMatch(/UvScale\b/);
+      expect(text, `${file} has fixed coordinate offsets`).not.toMatch(
+        /TEXTURE_COORDINATE_OFFSET|textureScaleOffset/,
+      );
+    }
+  });
+
+  it('routes every built-in material texture sample through the shared scale-aware helper', () => {
+    for (const file of shaderFiles) {
+      const text = source(file);
+      expect(text, `${file} imports the material sampling helper`).toContain(
+        'sampleMaterialTexture',
+      );
+      expect(text, `${file} has no direct material textureSample bypass`).not.toMatch(
+        /textureSample\((?:baseColor|metallicRoughness|normal|emissive|occlusion)Texture/,
+      );
+    }
+  });
+
+  it('documents the falsification boundary: replacing a non-unit scale with identity reaches padding', () => {
+    const scale: readonly [number, number] = [2085 / 2088, 1573 / 1576];
+    const [logicalX, logicalY] = scale;
+    const sabotagedEdge: readonly [number, number] = [1, 1];
+    expect(logicalX).toBeLessThan(sabotagedEdge[0]);
+    expect(logicalY).toBeLessThan(sabotagedEdge[1]);
+  });
+
+  it('keeps custom coordinate metadata distinct from texture resources', () => {
+    for (const file of shaderFiles) {
+      const text = source(file);
+      expect(text, `${file} must name coordinate metadata`).toMatch(/CoordinatesMetadata/);
+      expect(text, `${file} must preserve texture resources`).toMatch(/texture_2d|texture_cube/);
+    }
+  });
+});

package/src/__tests__/default-standard-pbr-alpha.unit.test.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const shader = readFileSync(
+  fileURLToPath(new URL('../default-standard-pbr.wgsl', import.meta.url)),
+  'utf8',
+);
+
+describe('standard PBR MASK alpha contract', () => {
+  it('multiplies factor alpha by sampled texture alpha before discard', () => {
+    expect(shader).toContain('alphaTest(material.baseColor.a * baseSample.a * vertexColor.a)');
+  });
+
+  it('matches Three r184 alphaTest by discarding values equal to or below cutoff', () => {
+    expect(shader).toContain('alpha <= material.alphaCutoff');
+    expect(shader).not.toContain('alpha < material.alphaCutoff');
+  });
+});

package/src/__tests__/deferred-lighting-ssao.test.ts

@@ -0,0 +1,114 @@
+// @forgeax/engine-shader/__tests__/deferred-lighting-ssao.test.ts -
+// Structural unit test for deferred lighting ambient SSAO synthesis (M2 / w11).
+// feat-20260612-hdrp-ssao.
+//
+// plan-strategy D-7: ambient *= mix(1.0, ssaoFactor * bakedAO, intensity).
+//
+// This test reads the deferred lighting entry point in default-standard-pbr.wgsl
+// and asserts:
+//   (a) ambient calculation contains mix(1.0, ...) with SSAO factor contribution
+//   (b) bakedAO is consumed in the ambient term (material.occlusionStrength)
+//   (c) SSAO texture read is optional (not required when SSAO absent)
+//   (d) Ambient formula = (kD * irradiance * albedo + specularIbl) * skylight.intensity * ao
+//       multiplied by SSAO blend when active
+//
+// RED before w12 (SSAO blend line not yet added to default-standard-pbr.wgsl).
+// GREEN after w12 inserts the synthesis line.
+
+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 pbrSource!: string;
+
+beforeAll(async () => {
+  const fsId = 'node:fs';
+  const pathId = 'node:path';
+  const urlId = 'node:url';
+  const 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);
+  const srcDir = path.resolve(path.dirname(here), '..');
+  pbrSource = fs.readFileSync(path.resolve(srcDir, 'default-standard-pbr.wgsl'), 'utf8');
+});
+
+function stripComments(src: string): string {
+  return src
+    .split(/\r?\n/)
+    .map((line: string) => line.replace(/\/\/.*$/, ''))
+    .join('\n');
+}
+
+describe('deferred lighting ambient SSAO synthesis (M2 / w11)', () => {
+  it('(a) ambient calculation uses occlusionStrength * bakedAO texture sample', () => {
+    // The ambient expression starts from kD * irradiance before clearcoat and
+    // skylight terms are applied; ao comes from material.occlusionStrength.
+    // M7/w32 changed `let` -> `var` so the SSAO blend line `ambient *= mix(...)` can mutate it.
+    const codeOnly = stripComments(pbrSource);
+    expect(codeOnly).toMatch(/var\s+ambient\s*=\s*\(*\s*kD\s*\*\s*irradiance/);
+    expect(codeOnly).toMatch(/material\.occlusionStrength/);
+    expect(codeOnly).toMatch(/skylight\.intensity/);
+  });
+
+  it('(b) SSAO blend formula ambient *= mix(1.0, ...) is present', () => {
+    // After w12, the source must contain the synthesis line:
+    //   ambient *= mix(1.0, ssaoFactor * bakedAO, intensity);
+    // or equivalent form.
+    const codeOnly = stripComments(pbrSource);
+    // Check for the mix(1.0, ...) pattern near or modifying the ambient variable.
+    expect(codeOnly).toMatch(/ambient\s*\*=\s*mix\(\s*1\.0\s*,\s*\w+/);
+  });
+
+  it('(c) SSAO factor is multiplied by ao (baked occlusion from texture)', () => {
+    // Verify the relationship: ssaoFactor * ao appears in the ambient modulation.
+    const codeOnly = stripComments(pbrSource);
+    // The formula is: ambient *= mix(1.0, ssaoFactor * ao, ssaoIntensity)
+    expect(codeOnly).toMatch(/ssaoFactor\s*\*\s*ao/);
+  });
+
+  it('(d) no crash path when SSAO texture absent (optional bind group)', () => {
+    // Verify the SSAO texture declaration is optional or conditional.
+    // When SSAO is not wired, the shader falls back to bakedAO-only.
+    // In the source: the ambient *= line should be conditional or use a
+    // default value when ssaoBlurred is not bound.
+    //
+    // For M2: the ambient line lives under CLUSTER_FORWARD_AVAILABLE ifdef
+    // or is guarded by a conditional. We verify that the SSAO-related
+    // variables (ssaoFactor, ssaoIntensity, ssaoBlurred) are used in
+    // a way that doesn't crash without binding.
+    const codeOnly = stripComments(pbrSource);
+    // The SSAO blend must appear near the ambient calculation in fs_main.
+    // Verify the fs_main function contains both the ambient calculation
+    // and the SSAO blend.
+    const ambientArea = codeOnly.slice(
+      codeOnly.indexOf('var ambient ='),
+      codeOnly.indexOf('var color = ambient'),
+    );
+    if (ambientArea.length > 0) {
+      // In the area between ambient calculation and color assignment,
+      // the SSAO blend should be present.
+      expect(ambientArea).toMatch(/ambient\s*\*=/);
+    }
+  });
+
+  it('(e) verify the exact formula: ambient *= mix(1.0, ssaoFactor * bakedAO, intensity)', () => {
+    // Numerical verification: when ssaoFactor=0.5, bakedAO=0.8, intensity=1.0:
+    //   mix(1.0, 0.5*0.8, 1.0) = mix(1.0, 0.4, 1.0) = 0.4
+    //   ambient *= 0.4 means the ambient term is reduced by 60%.
+    //
+    // We assert the source has the semantic shape of this formula.
+    const codeOnly = stripComments(pbrSource);
+    // Look for the exact pattern: ambient *= mix(1.0, <var> * <var>, <var>)
+    expect(codeOnly).toMatch(/ambient\s*\*=\s*mix\(\s*1\.0\s*,\s*\w+\s*\*\s*\w+\s*,\s*\w+\s*\)/);
+  });
+});