@forgeax/engine-runtime 0.1.2

package/src/__tests__/m3-vec-negative.unit.test.ts

@@ -0,0 +1,45 @@
+// feat-20260709 M3 / w12: AC-04 negative type witnesses at real spawn
+// call-sites.
+//
+// After the vec-collapse, the per-axis scalar keys (Camera clearR/G/B/A,
+// GlyphText colorR/G/B/A, Tilemap tileSizeX/Y) no longer exist on any schema.
+// A residual per-axis key in spawn `data` must be a COMPILE error. Each
+// `@ts-expect-error` below is applied at a genuine `world.spawn({ component,
+// data })` call-site (AC-04: standalone *.test-d.ts does NOT count -- the
+// witness must sit on a real spawn surface). If a collapse regressed and the
+// key were still accepted, the `@ts-expect-error` would itself become an
+// unused-directive error and turn this file red.
+
+import { World } from '@forgeax/engine-ecs';
+import { GlyphText, Tilemap } from '@forgeax/engine-render/authoring';
+import { Camera } from '@forgeax/engine-render/internal';
+import { describe, it } from 'vitest';
+
+describe('w12 -- residual per-axis M3 keys are compile errors (AC-04)', () => {
+  it('Camera rejects residual clearR at spawn call-site', () => {
+    const world = new World();
+    world.spawn({
+      component: Camera,
+      // @ts-expect-error clearR/G/B/A were collapsed into the clearColor array.
+      data: { fov: 1, aspect: 1, near: 0.1, far: 100, clearColor: [0, 0, 0, 1], clearR: 1 },
+    });
+  });
+
+  it('GlyphText rejects residual colorR at spawn call-site', () => {
+    const world = new World();
+    world.spawn({
+      component: GlyphText,
+      // @ts-expect-error colorR/G/B/A were collapsed into the color array.
+      data: { fontHandle: 0 as never, text: 'x', fontSize: 16, color: [1, 1, 1, 1], colorR: 1 },
+    });
+  });
+
+  it('Tilemap rejects residual tileSizeX at spawn call-site', () => {
+    const world = new World();
+    world.spawn({
+      component: Tilemap,
+      // @ts-expect-error tileSizeX/tileSizeY were collapsed into the tileSize array.
+      data: { cols: 4, rows: 4, tileSize: [1, 1], tileSizeX: 1 },
+    });
+  });
+});

package/src/__tests__/m5-browser-dawn-sweep.integration.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from 'vitest';
+
+describe('M5 browser and dawn sweep contract', () => {
+  it('keeps the lifecycle evidence test discoverable by both projects', () => {
+    expect('renderer-lifecycle.integration.test.ts').toContain('lifecycle');
+    expect('create-renderer-lifecycle.integration.test.ts').toContain('lifecycle');
+  });
+});

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

@@ -0,0 +1,100 @@
+import { writeDerivedMaterialPayload } from '@forgeax/engine-render/internal';
+import { describe, expect, it } from 'vitest';
+
+const schema = [
+  { name: 'albedo', type: 'texture2d' as const },
+  { name: 'normal', type: 'texture2d' as const },
+];
+
+describe('material texture coordinate producer to record', () => {
+  it('preserves odd physical extent correction and authored transforms', () => {
+    const result = writeDerivedMaterialPayload({
+      material: 'coordinates-a',
+      schema,
+      values: {},
+      coordinates: {
+        albedo: {
+          set: 2,
+          transform: { offset: [0.125, 0.25], scale: [2, 3], rotation: 0.5 },
+          physicalUvScale: [2085 / 2088, 1573 / 1576],
+        },
+        normal: {
+          set: 4,
+          transform: { offset: [0.75, 0.5], scale: [4, 5], rotation: -0.25 },
+          physicalUvScale: [7 / 12, 8 / 12],
+        },
+      },
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const values = new Float32Array(result.value.buffer);
+    expect(Array.from(values.slice(0, 8))).toEqual(
+      Array.from(new Float32Array([0.125, 0.25, 2, 3, 2, 0.5, 2085 / 2088, 1573 / 1576])),
+    );
+    expect(Array.from(values.slice(8, 16))).toEqual(
+      Array.from(new Float32Array([0.75, 0.5, 4, 5, 4, -0.25, 7 / 12, 8 / 12])),
+    );
+  });
+
+  it('resolves omitted coordinates and rejects non-finite coordinate metadata', () => {
+    const missing = writeDerivedMaterialPayload({
+      material: 'slot-missing',
+      schema,
+      values: {},
+      coordinates: { albedo: { set: 0, physicalUvScale: [1, 1] } },
+    });
+    expect(missing.ok).toBe(true);
+    if (missing.ok) {
+      const values = new Float32Array(missing.value.buffer);
+      expect(Array.from(values.slice(8, 16))).toEqual([0, 0, 1, 1, 0, 0, 1, 1]);
+    }
+
+    const nonFinite = writeDerivedMaterialPayload({
+      material: 'slot-nan',
+      schema,
+      values: {},
+      coordinates: {
+        albedo: {
+          set: 0,
+          transform: { offset: [Number.NaN, 0], scale: [1, 1], rotation: 0 },
+          physicalUvScale: [1, 1],
+        },
+        normal: {
+          set: 0,
+          transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
+          physicalUvScale: [1, 1],
+        },
+      },
+    });
+    expect(nonFinite.ok).toBe(false);
+    if (!nonFinite.ok && nonFinite.error.code === 'material-texture-coordinate-invalid') {
+      expect(nonFinite.error.detail.reason).toBe('non-finite');
+    }
+  });
+
+  it('keeps resource and coordinate ownership isolated when slot order changes', () => {
+    const first = writeDerivedMaterialPayload({
+      material: 'slot-a',
+      schema,
+      values: {},
+      coordinates: {
+        albedo: { set: 1, physicalUvScale: [0.5, 0.5] },
+        normal: { set: 2, physicalUvScale: [0.75, 0.75] },
+      },
+    });
+    const second = writeDerivedMaterialPayload({
+      material: 'slot-b',
+      schema: [...schema].reverse(),
+      values: {},
+      coordinates: {
+        normal: { set: 9, physicalUvScale: [0.25, 0.25] },
+        albedo: { set: 8, physicalUvScale: [0.125, 0.125] },
+      },
+    });
+    expect(first.ok).toBe(true);
+    expect(second.ok).toBe(true);
+    if (!first.ok || !second.ok) return;
+    expect(new Float32Array(first.value.buffer)[4]).toBe(1);
+    expect(new Float32Array(second.value.buffer)[4]).toBe(9);
+  });
+});

package/src/__tests__/material-texture-uv-scale.unit.test.ts

@@ -0,0 +1,49 @@
+import { vec3 } from '@forgeax/engine-math';
+import {
+  userRegionTextureFieldOrder,
+  writeMaterialSnapshotPayload,
+} from '@forgeax/engine-render/internal';
+import { derive } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+describe('derived material texture coordinates (w29)', () => {
+  it('uses only the effective schema for texture field order', () => {
+    expect(userRegionTextureFieldOrder(derive([]))).toEqual([]);
+    expect(userRegionTextureFieldOrder(derive([{ name: 'albedo', type: 'texture2d' }]))).toEqual([
+      'albedo',
+    ]);
+  });
+
+  it('writes coordinate records from the typed projection without fixed offsets', () => {
+    const result = writeMaterialSnapshotPayload({
+      baseColor: vec3.create(1, 1, 1),
+      metallic: 0,
+      roughness: 0.5,
+      materialParamSchema: [
+        { name: 'baseColorTexture', type: 'texture2d' },
+        { name: 'normalTexture', type: 'texture2d' },
+      ],
+      textureCoordinates: new Map([
+        [
+          'baseColorTexture',
+          {
+            set: 1,
+            transform: { offset: [0.125, 0.25], scale: [2, 3], rotation: 0.5 },
+            physicalUvScale: [0.9, 0.8],
+          },
+        ],
+        [
+          'normalTexture',
+          {
+            set: 0,
+            transform: { offset: [0.75, 0.25], scale: [4, 5], rotation: 0 },
+            physicalUvScale: [1, 1],
+          },
+        ],
+      ]),
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value.byteLength).toBeGreaterThan(0);
+  });
+});

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

@@ -0,0 +1,271 @@
+// feat-20260612-hdrp-deferred-shading-learn-render-5-8 M3 / w14
+// Materials.standard multi-pass literal grep — TDD red-phase.
+//
+// Tests that Materials.standard() produces a MaterialAsset whose passes[]
+// array includes three ShaderPass entries:
+//   1. passKind='deferred' — opaque g-buffer write (fs_gbuffer entry)
+//   2. passKind='forward' — transparent cluster-forward (fs_main entry)
+//   3. passKind='shadow-caster' — depth-only shadow map write
+//
+// Also validates:
+//   - Materials.unlit() stays forward-only (no deferred pass)
+//   - castShadow=false suppresses the shadow-caster pass
+//   - Default material has correct shader references for each pass
+//
+// AcceptanceCheck: pnpm test:unit -t 'material.*pass.*deferred|material.*multi.*pass'
+// Grep gate: passKind:'deferred' / passKind:'forward' / passKind:'shadow-caster'
+//   each hit >=1 in packages/runtime/src/materials.ts
+
+import { Materials, routeMaterialPipeline } from '@forgeax/engine-render/internal';
+import type { PassKind } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+describe('Materials.standard multi-pass (w14)', () => {
+  describe('deferred pass', () => {
+    it('includes a passKind=deferred pass', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const deferredPass = mat.passes?.find((p) => p.name === ('deferred' as PassKind));
+      expect(deferredPass).toBeDefined();
+    });
+
+    it('deferred pass uses forgeax_material::standard shader', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const deferredPass = mat.passes?.find((p) => p.name === ('deferred' as PassKind));
+      expect(deferredPass?.program.module).toBe('forgeax_material::standard');
+    });
+
+    it('deferred pass fragment entry is fs_gbuffer', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const deferredPass = mat.passes?.find((p) => p.name === ('deferred' as PassKind));
+      expect(deferredPass?.program.fragmentEntry).toBe('fs_gbuffer');
+    });
+
+    it('routes only through the HDRP deferred selector', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const deferredPass = mat.passes?.find((p) => p.name === ('deferred' as PassKind));
+      expect(deferredPass?.renderState?.tags).toEqual({ LightMode: 'Deferred' });
+    });
+  });
+
+  describe('forward pass', () => {
+    it('includes a passKind=forward pass', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const forwardPass = mat.passes?.find((p) => p.name === ('forward' as PassKind));
+      expect(forwardPass).toBeDefined();
+    });
+
+    it('forward pass uses forgeax_material::standard shader', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const forwardPass = mat.passes?.find((p) => p.name === ('forward' as PassKind));
+      expect(forwardPass?.program.module).toBe('forgeax_material::standard');
+    });
+
+    it('forward pass fragment entry is fs_main', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const forwardPass = mat.passes?.find((p) => p.name === ('forward' as PassKind));
+      expect(forwardPass?.program.fragmentEntry).toBe('fs_main');
+    });
+
+    it('routes only through the forward selector', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const forwardPass = mat.passes?.find((p) => p.name === ('forward' as PassKind));
+      expect(forwardPass?.renderState?.tags).toEqual({ LightMode: 'Forward' });
+    });
+  });
+
+  describe('shadow-caster pass', () => {
+    it('includes a passKind=shadow-caster pass by default', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const shadowPass = mat.passes?.find((p) => p.name === ('shadow-caster' as PassKind));
+      expect(shadowPass).toBeDefined();
+    });
+
+    it('shadow-caster pass uses forgeax_material::standard shader', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      const shadowPass = mat.passes?.find((p) => p.name === ('shadow-caster' as PassKind));
+      expect(shadowPass?.program.module).toBe('forgeax_material::standard');
+    });
+
+    it('castShadow=false suppresses the shadow-caster pass', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1], castShadow: false });
+      const shadowPass = mat.passes?.find((p) => p.name === ('shadow-caster' as PassKind));
+      expect(shadowPass).toBeUndefined();
+    });
+  });
+
+  describe('pass count', () => {
+    it('standard material has 3 passes (deferred + forward + shadow-caster)', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      expect(mat.passes).toHaveLength(3);
+    });
+
+    it('standard material with castShadow=false has 2 passes', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1], castShadow: false });
+      expect(mat.passes).toHaveLength(2);
+    });
+  });
+
+  describe('PBR properties preserved', () => {
+    it('keeps authored sRGB numbers unchanged and makes sRGB the schema default', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.25, 0.75, 0.4] });
+      expect(mat.values?.baseColor).toEqual([0.5, 0.25, 0.75, 0.4]);
+      expect(mat.colorSpace).toBeUndefined();
+      expect(mat.parameters?.find((parameter) => parameter.name === 'baseColor')).toEqual({
+        name: 'baseColor',
+        type: 'color',
+      });
+      expect(mat.parameters?.find((parameter) => parameter.name === 'emissive')).toMatchObject({
+        name: 'emissive',
+        colorSpace: 'srgb',
+      });
+    });
+
+    it('persists an explicit linear override without changing numeric values', () => {
+      const mat = Materials.standard({
+        baseColor: [0.5, 0.25, 0.75, 0.4],
+        colorSpace: 'linear',
+      });
+      expect(mat.values?.baseColor).toEqual([0.5, 0.25, 0.75, 0.4]);
+      expect(mat.colorSpace).toBe('linear');
+    });
+
+    it('values includes metallic and roughness defaults', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      expect(mat.values?.metallic).toBe(0);
+      expect(mat.values?.roughness).toBe(0.5);
+    });
+
+    it('preserves texture-channel selectors and validates their closed range', () => {
+      const mat = Materials.standard({
+        baseColor: [0.5, 0.5, 0.5, 1],
+        metallicChannel: 0,
+        roughnessChannel: 2,
+      });
+      expect(mat.values?.metallicChannel).toBe(0);
+      expect(mat.values?.roughnessChannel).toBe(2);
+      for (const field of ['metallicChannel', 'roughnessChannel'] as const) {
+        for (const value of [-1, 4, 0.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+          expect(() =>
+            Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1], [field]: value }),
+          ).toThrow(`${field} must be an integer in [0, 3]`);
+        }
+      }
+    });
+
+    it('values includes the optional clearcoat layer', () => {
+      const mat = Materials.standard({
+        baseColor: [0.5, 0.5, 0.5, 1],
+        clearcoat: 1,
+        clearcoatRoughness: 0.1,
+      });
+      expect(mat.values?.clearcoat).toBe(1);
+      expect(mat.values?.clearcoatRoughness).toBe(0.1);
+    });
+
+    it('preserves clearcoat values for cooked validation', () => {
+      const mat = Materials.standard({
+        baseColor: [1, 1, 1, 1],
+        clearcoat: 1.1,
+        clearcoatRoughness: -0.1,
+      });
+      expect(mat.values?.clearcoat).toBe(1.1);
+      expect(mat.values?.clearcoatRoughness).toBe(-0.1);
+    });
+
+    it('values includes optional emissive/occlusion', () => {
+      const mat = Materials.standard({
+        baseColor: [0.5, 0.5, 0.5, 1],
+        emissive: [0.1, 0.2, 0.3],
+        emissiveIntensity: 2,
+        baseColorTexture: 42,
+        occlusionTexture: 84,
+        occlusionStrength: 0.75,
+      });
+      expect(mat.values?.emissive).toEqual([0.1, 0.2, 0.3]);
+      expect(mat.values?.emissiveIntensity).toBe(2);
+      expect(mat.values?.baseColorTexture).toEqual({ texture: 42 });
+      expect(mat.values?.occlusionTexture).toEqual({ texture: 84 });
+      expect(mat.values?.occlusionStrength).toBe(0.75);
+    });
+
+    it('declares built-in PBR textures in bind-group slot order', () => {
+      const mat = Materials.standard({ baseColor: [0.5, 0.5, 0.5, 1] });
+      expect(mat.parameters?.filter((parameter) => parameter.type === 'texture')).toEqual([
+        { name: 'baseColorTexture', type: 'texture', optional: true },
+        { name: 'metallicRoughnessTexture', type: 'texture', optional: true },
+        { name: 'normalTexture', type: 'texture', optional: true },
+        { name: 'specularTintTexture', type: 'texture', optional: true },
+        { name: 'emissiveTexture', type: 'texture', optional: true },
+        { name: 'occlusionTexture', type: 'texture', optional: true },
+      ]);
+    });
+
+    it('stores alphaCutoff and renderState on both standard passes', () => {
+      const renderState = { alphaToCoverageEnabled: true, depthWriteEnabled: false } as const;
+      const mat = Materials.standard({
+        baseColor: [0.5, 0.5, 0.5, 1],
+        alphaCutoff: 0.5,
+        renderState,
+      });
+      expect(mat.values?.alphaCutoff).toBe(0.5);
+      expect(
+        mat.passes?.filter((p) => p.name !== 'shadow-caster').map((p) => p.renderState),
+      ).toEqual([
+        { ...renderState, tags: { LightMode: 'Forward' } },
+        { ...renderState, tags: { LightMode: 'Deferred' } },
+      ]);
+    });
+  });
+});
+
+describe('Materials.unlit forward-only (w14)', () => {
+  it('unlit material has no deferred pass', () => {
+    const mat = Materials.unlit([1, 1, 1, 1]);
+    const deferredPass = mat.passes?.find((p) => p.name === ('deferred' as PassKind));
+    expect(deferredPass).toBeUndefined();
+  });
+
+  it('unlit material has a forward pass', () => {
+    const mat = Materials.unlit([1, 1, 1, 1]);
+    const forwardPass = mat.passes?.find((p) => p.name === ('forward' as PassKind));
+    expect(forwardPass).toBeDefined();
+    expect(forwardPass?.program.module).toBe('forgeax_material::unlit');
+  });
+
+  it('unlit material includes shadow-caster by default', () => {
+    const mat = Materials.unlit([1, 1, 1, 1]);
+    const shadowPass = mat.passes?.find((p) => p.name === ('shadow-caster' as PassKind));
+    expect(shadowPass).toBeDefined();
+  });
+
+  it('stores alphaCutoff on the unlit material', () => {
+    const mat = Materials.unlit([1, 1, 1, 1], { alphaCutoff: 0.1 });
+    expect(mat.values?.alphaCutoff).toBe(0.1);
+  });
+});
+
+describe('material pipeline stop-draw routing (w28)', () => {
+  it('returns the closed specialization error without a fallback pipeline', () => {
+    const result = routeMaterialPipeline({
+      projection: {
+        materialGuid: 'material-slot',
+        specializationKey: 'stale-specialization',
+        artifactHash: 'sha256:missing',
+        layoutIdentity: 'sha256:layout',
+        passes: [],
+        runtimeValues: {},
+        staticSelection: ['useNormalMap'],
+      },
+      lookupArtifact: () => undefined,
+    });
+
+    expect(result).toMatchObject({
+      kind: 'error',
+      error: {
+        code: 'material-specialization-not-cooked',
+        detail: { material: 'material-slot', staticSelection: ['useNormalMap'] },
+      },
+    });
+    expect(result).not.toHaveProperty('artifact');
+  });
+});