@forgeax/engine-shader 0.1.2

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

@@ -0,0 +1,111 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { derive } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  BUILTIN_MATERIAL_MODULES,
+  type BuiltinMaterialKind,
+  createBuiltinMaterialAsset,
+  isEngineMaterial,
+  isEngineMaterialModule,
+} from '../index.js';
+import type { MaterialShaderArtifact } from '../material/artifact-types.js';
+import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '../material-schemas.js';
+
+const builtinSources = [
+  'default-standard-pbr.wgsl',
+  'default-standard-pbr-skin.wgsl',
+  'unlit.wgsl',
+  'sprite.wgsl',
+  'sprite-lit.wgsl',
+  'msdf-text.wgsl',
+] as const;
+
+const kinds: readonly BuiltinMaterialKind[] = ['standard', 'unlit', 'sprite'];
+
+function source(file: string): string {
+  return readFileSync(fileURLToPath(new URL(`../${file}`, import.meta.url)), 'utf8');
+}
+
+describe('built-in MaterialAsset sources', () => {
+  it('keeps Engine-owned module identity in one shared predicate', () => {
+    expect(isEngineMaterial(createBuiltinMaterialAsset('standard'))).toBe(true);
+    expect(isEngineMaterialModule('forgeax::default-standard-pbr')).toBe(true);
+    expect(isEngineMaterialModule('game::custom')).toBe(false);
+    expect(
+      isEngineMaterial({
+        passes: [{ name: 'forward', program: { module: 'game::custom' } }],
+      }),
+    ).toBe(false);
+  });
+
+  it.each(kinds)('uses one authored MaterialAsset contract for %s', (kind) => {
+    const material = createBuiltinMaterialAsset(kind);
+    const pass = material.passes?.[0];
+
+    expect(material.kind).toBe('material');
+    expect(pass?.program.module).toBe(BUILTIN_MATERIAL_MODULES[kind]);
+    expect(pass).not.toHaveProperty('shader');
+    expect(material.parameters?.length).toBeGreaterThan(0);
+    expect(material.values).toBeDefined();
+  });
+
+  it('keeps cooked artifact identity separate from authored values', () => {
+    const material = createBuiltinMaterialAsset('standard');
+    const artifact: MaterialShaderArtifact = {
+      material: 'builtin-standard',
+      pass: material.passes?.[0]?.name ?? 'forward',
+      wgsl: 'builtin-standard-wgsl',
+      layoutIdentity: 'sha256-builtin-standard-layout',
+      bindings: [],
+      deps: [BUILTIN_MATERIAL_MODULES.standard],
+      vertexInputs: [],
+      specializationKey: 'builtin-standard-key',
+    };
+
+    expect(artifact.specializationKey).toBe('builtin-standard-key');
+    expect(artifact.deps).toEqual([BUILTIN_MATERIAL_MODULES.standard]);
+    expect(material.values?.baseColor).toEqual([1, 1, 1, 1]);
+    expect(
+      { ...material, values: { ...material.values, baseColor: [0.2, 0.3, 0.4, 1] } }.values,
+    ).toMatchObject({ baseColor: [0.2, 0.3, 0.4, 1] });
+  });
+});
+
+describe('built-in and custom material derived layout matrix', () => {
+  it('models emissive and occlusion as real standard material texture parameters', () => {
+    const names = DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => entry.name);
+    expect(names).toContain('emissiveTexture');
+    expect(names).toContain('occlusionTexture');
+    expect(
+      DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter((entry) => entry.type === 'texture2d'),
+    ).toHaveLength(6);
+  });
+
+  it('derives a coordinate record for every texture parameter in an interleaved custom schema', () => {
+    const derived = derive([
+      { name: 'before', type: 'vec4' },
+      { name: 'albedo', type: 'texture2d' },
+      { name: 'roughness', type: 'f32' },
+      { name: 'normal', type: 'texture2d' },
+    ]);
+    expect(derived.coordinateRecords.map((record) => record.parameter)).toEqual([
+      'albedo',
+      'normal',
+    ]);
+    expect(derived.coordinateRecords.every((record) => record.size === 32)).toBe(true);
+    expect(derived.coordinateRecords[0]?.offset).not.toBe(derived.coordinateRecords[1]?.offset);
+  });
+
+  it('keeps the built-in source matrix on the derived coordinate contract', () => {
+    for (const file of builtinSources) {
+      const text = source(file);
+      expect(text, `${file} must expose derived coordinate members`).toContain(
+        'CoordinatesTransform',
+      );
+      expect(text, `${file} must not carry a fixed coordinate tail`).not.toContain(
+        'textureScalePadding',
+      );
+    }
+  });
+});

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

@@ -0,0 +1,79 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { describe, expect, it } from 'vitest';
+import { MaterialArtifactRegistry } from '../material/artifact-registry.js';
+import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '../material-schemas.js';
+
+const alphaSchema = JSON.parse(
+  readFileSync(
+    fileURLToPath(
+      new URL(
+        '../../../../apps/parity/color-lighting/schemas/material-alpha.schema.json',
+        import.meta.url,
+      ),
+    ),
+    'utf8',
+  ),
+) as object;
+const validateAlpha = new Ajv2020({ allErrors: true, strict: false }).compile(alphaSchema);
+
+describe('standard PBR material alpha contract', () => {
+  it('keeps one immutable cooked artifact per specialization key', () => {
+    const registry = new MaterialArtifactRegistry();
+    const first = registry.register({
+      key: 'forgeax::standard:forward',
+      bytes: Uint8Array.of(1, 2, 3),
+      digest: 'sha256:standard-forward',
+    });
+    const conflict = registry.register({
+      key: 'forgeax::standard:forward',
+      bytes: Uint8Array.of(9),
+      digest: 'sha256:changed',
+    });
+
+    expect(first.ok).toBe(true);
+    expect(conflict).toMatchObject({
+      ok: false,
+      error: { code: 'material-artifact-conflict', detail: { key: 'forgeax::standard:forward' } },
+    });
+  });
+
+  it('owns RGBA and factor-times-texture alpha in the baseColor schema', () => {
+    const baseColor = DEFAULT_STANDARD_PBR_PARAM_SCHEMA.find((entry) => entry.name === 'baseColor');
+    const alphaCutoff = DEFAULT_STANDARD_PBR_PARAM_SCHEMA.find(
+      (entry) => entry.name === 'alphaCutoff',
+    );
+
+    expect(baseColor).toMatchObject({
+      name: 'baseColor',
+      type: 'color',
+      default: [1, 1, 1, 1],
+    });
+    expect(alphaCutoff).toMatchObject({ name: 'alphaCutoff', type: 'f32' });
+    expect(DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => entry.name)).not.toContain(
+      'baseColorAlpha',
+    );
+    expect(DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => entry.name)).not.toContain(
+      'textureAlphaFactor',
+    );
+  });
+
+  it.each([
+    ['short RGBA', { baseColor: [1, 1, 1], alphaMode: 'MASK' }],
+    ['unknown alpha mode', { baseColor: [1, 1, 1, 1], alphaMode: 'DITHER' }],
+    ['negative cutoff', { baseColor: [1, 1, 1, 1], alphaMode: 'MASK', alphaCutoff: -0.1 }],
+  ])('rejects %s before GPU execution', (_name, value) => {
+    expect(validateAlpha(value)).toBe(false);
+  });
+
+  it('keeps the glTF MASK default cutoff explicit in the schema', () => {
+    const properties = alphaSchema as {
+      readonly properties?: {
+        readonly alphaCutoff?: { readonly default?: number };
+      };
+    };
+    expect(properties.properties?.alphaCutoff?.default).toBe(0.5);
+    expect(validateAlpha({ baseColor: [1, 1, 1, 0.5], alphaMode: 'MASK' })).toBe(true);
+  });
+});

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

@@ -0,0 +1,30 @@
+import { derive } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '../material-schemas.js';
+
+describe('material derived built-in integration contract', () => {
+  it('uses the same derived identity for standard and skinned standard schemas', () => {
+    const standard = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
+    const skinned = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
+    expect(skinned.layoutIdentity).toBe(standard.layoutIdentity);
+    expect(skinned.totalBytes).toBe(standard.totalBytes);
+  });
+
+  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(
+      (entry) => entry.type === 'texture2d',
+    ).map((entry) => entry.name);
+    expect(derived.coordinateRecords.map((record) => record.parameter)).toEqual(textureNames);
+    expect(
+      derived.coordinateRecords.every((record) =>
+        record.transformMember.endsWith('CoordinatesTransform'),
+      ),
+    ).toBe(true);
+    expect(
+      derived.coordinateRecords.every((record) =>
+        record.metadataMember.endsWith('CoordinatesMetadata'),
+      ),
+    ).toBe(true);
+  });
+});

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

@@ -0,0 +1,9 @@
+import { describe, expect, test } from 'vitest';
+import * as publicSurface from '../index.js';
+
+describe('shader public surface', () => {
+  test('keeps the runtime registry without a version mirror', () => {
+    expect(typeof publicSurface.ShaderRegistry).toBe('function');
+    expect('SHADER_PACKAGE_VERSION' in publicSurface).toBe(false);
+  });
+});

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

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const localTemporalShaders = ['unlit.wgsl', 'sprite.wgsl', 'sprite-lit.wgsl'] as const;
+
+const pbrTemporalConsumers = [
+  'default-standard-pbr.wgsl',
+  'default-standard-pbr-skin.wgsl',
+] as const;
+
+describe('scene temporal varyings', () => {
+  it.each(localTemporalShaders)('%s linearly interpolates both clip authorities', (file) => {
+    const source = readFileSync(resolve(import.meta.dirname, '..', file), 'utf8');
+    expect(source).toMatch(/@interpolate\(linear\) currentClip : vec4<f32>/);
+    expect(source).toMatch(/@interpolate\(linear\) previousClip : vec4<f32>/);
+  });
+
+  it('keeps PBR UV selection and fragment projection in one module', () => {
+    const source = readFileSync(resolve(import.meta.dirname, '..', 'pbr-temporal.wgsl'), 'utf8');
+    expect(source).toContain('fn transformedPbrTemporalUv');
+    expect(source).toContain('fn projectPbrSceneTemporal');
+  });
+
+  it.each(pbrTemporalConsumers)('%s imports the shared PBR temporal authority', (file) => {
+    const source = readFileSync(resolve(import.meta.dirname, '..', file), 'utf8');
+    expect(source).toContain('#import forgeax_pbr::temporal::{projectPbrSceneTemporal}');
+    expect(source).toMatch(/@interpolate\(linear\) currentClip : vec4<f32>/);
+    expect(source).toMatch(/@interpolate\(linear\) previousClip : vec4<f32>/);
+    expect(source).not.toContain('fn transformedTemporalUv');
+  });
+});

package/src/__tests__/shader-registry-transaction.unit.test.ts

@@ -0,0 +1,116 @@
+import type { ShaderModule } from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
+import { type ManifestEntry, ShaderRegistry, type ShaderRegistryDevice } from '../index.js';
+
+const FIRST_ENTRY: ManifestEntry = {
+  hash: 'first123',
+  wgsl: 'first-wgsl',
+  glsl: undefined,
+  bindings: '[]',
+};
+
+const SECOND_ENTRY: ManifestEntry = {
+  hash: 'second12',
+  wgsl: 'second-wgsl',
+  glsl: '',
+  bindings: '[]',
+};
+
+const CORRECTED_MATERIAL_SHADER = {
+  identifier: 'my-game::corrected',
+  sourcePath: 'src/corrected.wgsl',
+  composedWgsl: 'corrected-wgsl',
+  paramSchema: '[]',
+  variants: [],
+};
+
+const CORRECTED_MANIFEST = {
+  entries: [SECOND_ENTRY, FIRST_ENTRY],
+  materialShaders: [CORRECTED_MATERIAL_SHADER],
+};
+
+function createTrackingDevice(): { device: ShaderRegistryDevice; created: string[] } {
+  const created: string[] = [];
+  const device: ShaderRegistryDevice = {
+    createShaderModule({ code }) {
+      created.push(code);
+      return {
+        ok: true,
+        value: {} as ShaderModule,
+      } as ReturnType<ShaderRegistryDevice['createShaderModule']>;
+    },
+  };
+  return { device, created };
+}
+
+function dataUrl(): string {
+  return 'data:application/json,shader-registry-transaction';
+}
+
+describe('ShaderRegistry public manifest transaction', () => {
+  it.each([
+    {
+      name: 'a malformed later entry',
+      manifest: {
+        entries: [FIRST_ENTRY, { ...SECOND_ENTRY, bindings: 42 }],
+        materialShaders: [CORRECTED_MATERIAL_SHADER],
+      },
+    },
+    {
+      name: 'a malformed material row',
+      manifest: {
+        entries: [FIRST_ENTRY, SECOND_ENTRY],
+        materialShaders: [{ identifier: 'my-game::malformed' }],
+      },
+    },
+  ])('refuses $name atomically and retries the same source on the same registry', async ({
+    manifest,
+  }) => {
+    let currentManifest: unknown = manifest;
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
+      return new Response(JSON.stringify(currentManifest), {
+        headers: { 'content-type': 'application/json' },
+      });
+    });
+    const { device, created } = createTrackingDevice();
+    const manifestUrl = dataUrl();
+    const registry = new ShaderRegistry({ device, manifestUrl });
+
+    try {
+      const refused = await registry.loadManifest();
+      expect(refused.ok).toBe(false);
+      if (refused.ok) return;
+      expect(refused.error.code).toBe('manifest-malformed');
+      expect(Array.from(registry.entries())).toEqual([]);
+      expect(Array.from(registry.materialShaderManifestEntries())).toEqual([]);
+      expect(registry.get(FIRST_ENTRY.hash).ok).toBe(false);
+      expect(created).toEqual([]);
+
+      currentManifest = CORRECTED_MANIFEST;
+      const repaired = await registry.loadManifest();
+      expect(repaired.ok).toBe(true);
+      expect(Array.from(registry.entries()).map((entry) => entry.hash)).toEqual([
+        SECOND_ENTRY.hash,
+        FIRST_ENTRY.hash,
+      ]);
+      expect(
+        Array.from(registry.materialShaderManifestEntries()).map((entry) => entry.identifier),
+      ).toEqual([CORRECTED_MATERIAL_SHADER.identifier]);
+
+      const module = registry.get(SECOND_ENTRY.hash);
+      expect(module.ok).toBe(true);
+      expect(created).toEqual([SECOND_ENTRY.wgsl]);
+
+      const reloaded = await registry.loadManifest();
+      expect(reloaded.ok).toBe(true);
+      expect(fetchSpy).toHaveBeenCalledTimes(2);
+      expect(Array.from(registry.entries()).map((entry) => entry.hash)).toEqual([
+        SECOND_ENTRY.hash,
+        FIRST_ENTRY.hash,
+      ]);
+      expect(created).toEqual([SECOND_ENTRY.wgsl]);
+    } finally {
+      fetchSpy.mockRestore();
+    }
+  });
+});