@forgeax/engine-render 0.1.33 → 0.1.34

package/src/__tests__/material-shader-prewarm.unit.test.ts

@@ -0,0 +1,59 @@
+import type { RhiDevice, ShaderModule } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import type { ShaderCatalog } from '@forgeax/engine-shader';
+import { describe, expect, it, vi } from 'vitest';
+import { prepareLowLimitMaterialShaderEntry } from '../assembly/material-shader-policy';
+import { prewarmRequiredMaterialShaders } from '../assembly/material-shader-prewarm';
+
+const source = `
+@group(0) @binding(16) var cloud: texture_2d<f32>;
+@group(0) @binding(17) var cloudSampler: sampler;
+fn sampleCloud() -> f32 {
+  return textureSampleLevel(cloud, cloudSampler, vec2<f32>(0.5), 0.0).x;
+}`;
+
+describe('material module prewarm and lazy pipeline agreement', () => {
+  it.each([16, 32])('seeds the same source on a %i-texture device', async (limit) => {
+    const entry = { source, paramSchema: [] };
+    const variantSource = `${source}\n// published variant`;
+    const registry = {
+      findMaterialArtifact: () => ok(entry),
+      materialShaderManifestEntries: () =>
+        [
+          {
+            identifier: 'game::surface',
+            variants: [{ definesKey: 'STYLE=true', composedWgsl: variantSource }],
+          },
+        ][Symbol.iterator](),
+    } as unknown as ShaderCatalog;
+    const device = { limits: { maxSampledTexturesPerShaderStage: limit } } as RhiDevice;
+    const compiled = new Map<ShaderModule, string>();
+    const seeded = new Map<string, ShaderModule>();
+    const compile = vi.fn(async (_device: RhiDevice, descriptor: { code: string }) => {
+      const module = {} as ShaderModule;
+      compiled.set(module, descriptor.code);
+      return ok(module);
+    });
+    await prewarmRequiredMaterialShaders({
+      rhiDevice: device,
+      registry,
+      requiredMaterialShaders: ['game::surface'],
+      asyncCreateShaderModule: compile,
+      seedShaderModule: (label, module) => {
+        seeded.set(label, module);
+      },
+    });
+    for (const [label, authored] of [
+      ['module-game::surface', source],
+      ['module-game::surface#STYLE=true', variantSource],
+    ] as const) {
+      const module = seeded.get(label);
+      expect(module).toBeDefined();
+      if (module === undefined) throw new Error(`Missing prewarmed module ${label}`);
+      expect(compiled.get(module)).toBe(
+        prepareLowLimitMaterialShaderEntry({ source: authored, paramSchema: [] }, limit).source,
+      );
+    }
+    expect(entry.source).toBe(source);
+  });
+});

package/src/__tests__/material-snapshot-mutation.integration.test.ts

@@ -8,9 +8,47 @@ import { describe, expect, it } from 'vitest';
 import { projectStandardSurfacePasses } from '../assembly/material/surface-projection';
 import { MeshFilter } from '../components/mesh-filter';
 import { MeshRenderer } from '../components/mesh-renderer';
-import { extractFrames, type MaterialSnapshotCachesByWorld } from '../render-system-extract';
+import {
+  extractFrames,
+  type MaterialSnapshotCachesByWorld,
+  resolveMaterialSnapshot,
+} from '../render-system-extract';
 
 describe('material snapshot mutation', () => {
+  it('projects the same Surface model for primary and reusable submesh snapshots', () => {
+    const world = new World();
+    const assets = new AssetRegistry({
+      findMaterialArtifact: () => ({ ok: false, error: new Error('not registered') }),
+    } as unknown as ShaderRegistry);
+    const material: MaterialAsset = {
+      kind: 'material',
+      surface: {
+        model: 'single-layer-medium',
+        module: 'game::water-surface',
+      },
+      passes: [
+        {
+          name: 'color',
+          program: { module: 'forgeax::single-layer-medium' },
+          renderState: { tags: { LightMode: 'Forward' }, queue: 3000 },
+        },
+      ],
+      values: {},
+    };
+    const materialHandle = world.allocSharedRef('MaterialAsset', material);
+    world.spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [materialHandle] } },
+    );
+
+    const primary = extractFrames([world], 0, assets).renderables[0]?.material;
+    const reusable = resolveMaterialSnapshot(materialHandle, world, assets);
+
+    expect(primary?.surfaceModel).toBe('single-layer-medium');
+    expect(reusable.surfaceModel).toBe('single-layer-medium');
+  });
+
   it('projects in-place material value updates into the next extracted frame', () => {
     const world = new World();
     const assets = new AssetRegistry({

package/src/__tests__/morph-culling-reentry.dawn.test.ts

@@ -70,7 +70,7 @@ describe('Morph GPU culling and re-entry', () => {
     ).toMatchObject({ reentered: true, clearStale: true, weights: [0.75] });
   });
 
-  it('declares compute and storage capability ownership and records 300 frame phases', () => {
+  it('declares compute and storage capability ownership and records 60 frame phases', () => {
     let frameNumber = 0;
     const feature = createBuiltinMorphFeature({
       collect: () => [
@@ -79,8 +79,8 @@ describe('Morph GPU culling and re-entry', () => {
           vertexCount: 3,
           targetBounds: [{ min: [-2, 0, 0], max: [3, 0, 0] }],
           baseBounds,
-          weights: new Float32Array([frameNumber >= 200 ? 1 : 0]),
-          baseAabbIntersectsFrustum: frameNumber < 100 || frameNumber >= 200,
+          weights: new Float32Array([frameNumber >= 40 ? 1 : 0]),
+          baseAabbIntersectsFrustum: frameNumber < 20 || frameNumber >= 40,
         },
       ],
     });
@@ -88,7 +88,7 @@ describe('Morph GPU culling and re-entry', () => {
     expect(feature.requiredCapabilities).toEqual(['compute', 'storageBuffer']);
     let culledFrames = 0;
     let reentries = 0;
-    for (frameNumber = 0; frameNumber < 300; frameNumber++) {
+    for (frameNumber = 0; frameNumber < 60; frameNumber++) {
       const extracted = feature.extract({ worlds: [], owner: 0, frameNumber });
       expect(extracted.ok).toBe(true);
       if (!extracted.ok) continue;
@@ -96,7 +96,7 @@ describe('Morph GPU culling and re-entry', () => {
       reentries += extracted.value.reentryCount;
     }
 
-    expect(culledFrames).toBe(100);
+    expect(culledFrames).toBe(20);
     expect(reentries).toBe(1);
   });
 

package/src/__tests__/morph-visual-evidence.integration.test.ts

@@ -11,7 +11,7 @@ const evidencePath = resolve(
 const matrixPath = resolve(repoRoot, 'apps/hello/format-tier1/evidence/format-support-matrix.json');
 
 describe('Morph Dawn evidence contract', () => {
-  it('binds the 300-frame GPU result to the immutable source and readback', async () => {
+  it('binds a complete GPU result of at least 60 frames to the immutable source and readback', async () => {
     const [evidence, matrix] = await Promise.all([
       readFile(evidencePath, 'utf8').then(
         (source) =>
@@ -54,13 +54,14 @@ describe('Morph Dawn evidence contract', () => {
     expect(matrix.source?.firstTierRows).toEqual([8, 18, 26]);
     expect(evidence.source?.sourceCodeSha).toMatch(/^[a-f0-9]{40,64}$/);
     expect(evidence.environment?.backend).toBe('dawn');
-    expect(evidence.requiredFrames).toBe(300);
-    expect(evidence.framesObserved).toBe(300);
+    expect(evidence.requiredFrames).toBeGreaterThanOrEqual(60);
+    expect(evidence.framesObserved).toBe(evidence.requiredFrames);
+    const phaseFrames = (evidence.requiredFrames ?? 0) / 3;
     expect(evidence.phases).toEqual({
-      standardFrames: 300,
-      baseWeightFrames: 100,
-      zeroWeightFrames: 100,
-      animatedFrames: 100,
+      standardFrames: evidence.requiredFrames,
+      baseWeightFrames: phaseFrames,
+      zeroWeightFrames: phaseFrames,
+      animatedFrames: phaseFrames,
     });
     expect(evidence.readback?.status).toBe('pass');
     expect(evidence.readback?.path).toContain('observe(FrameReceipt)');

package/src/__tests__/motion-blur-compute.dawn.test.ts

@@ -538,7 +538,8 @@ it.each(PROBES)('production compute lane: $name', async ({
     } else {
       expect(receiver, `${name} outside-support receiver unexpectedly received motion`).toBe(0);
     }
-    const decodeFloat16 = (bits: number): number => {
+    const decodeFloat16 = (bits: number | undefined): number => {
+      if (bits === undefined) throw new Error('Readback omitted a required pixel');
       const sign = (bits & 0x8000) === 0 ? 1 : -1;
       const exponent = (bits >>> 10) & 0x1f;
       const mantissa = bits & 0x03ff;
@@ -547,9 +548,11 @@ it.each(PROBES)('production compute lane: $name', async ({
       return sign * 2 ** (exponent - 15) * (1 + mantissa / 1024);
     };
     if (expectedRowEnergy !== undefined) {
-      const rowEnergy = Array.from({ length: width }, (_, x) =>
-        decodeFloat16(result[receiverY * (readbackBytesPerRow / 2) + x * 4]),
-      ).reduce((sum, value) => sum + value, 0);
+      const rowEnergy = Array.from({ length: width }, (_, x) => {
+        const bits = result[receiverY * (readbackBytesPerRow / 2) + x * 4];
+        if (bits === undefined) throw new Error(`${name} row readback is truncated at x=${x}`);
+        return decodeFloat16(bits);
+      }).reduce((sum, value) => sum + value, 0);
       const relativeError =
         Math.abs(rowEnergy - expectedRowEnergy) / Math.max(expectedRowEnergy, 1);
       expect(
@@ -559,9 +562,12 @@ it.each(PROBES)('production compute lane: $name', async ({
     }
     if (expectedTotalEnergy !== undefined) {
       const totalEnergy = Array.from({ length: height }, (_, y) =>
-        Array.from({ length: width }, (_, x) =>
-          decodeFloat16(result[y * (readbackBytesPerRow / 2) + x * 4]),
-        ).reduce((sum, value) => sum + value, 0),
+        Array.from({ length: width }, (_, x) => {
+          const bits = result[y * (readbackBytesPerRow / 2) + x * 4];
+          if (bits === undefined)
+            throw new Error(`${name} total readback is truncated at y=${y}, x=${x}`);
+          return decodeFloat16(bits);
+        }).reduce((sum, value) => sum + value, 0),
       ).reduce((sum, value) => sum + value, 0);
       const relativeError =
         Math.abs(totalEnergy - expectedTotalEnergy) / Math.max(expectedTotalEnergy, 1);

package/src/__tests__/motion-blur.pixel.integration.test.ts

@@ -84,8 +84,8 @@ describe('motion blur visual evidence contract', () => {
       expect(entry.falsifier.provenance.length).toBeGreaterThan(0);
       expect(entry.positive.confidence).toBeGreaterThanOrEqual(0);
       expect(entry.falsifier.confidence).toBeGreaterThanOrEqual(0);
-      expect(entry.positive.coverage.dawnFrames).toBeGreaterThanOrEqual(300);
-      expect(entry.positive.coverage.browserFrames).toBeGreaterThanOrEqual(300);
+      expect(entry.positive.coverage.dawnFrames).toBeGreaterThanOrEqual(60);
+      expect(entry.positive.coverage.browserFrames).toBeGreaterThanOrEqual(60);
       expect(entry.positive.coverage.frames).toBe(entry.positive.coverage.dawnFrames);
       expect(entry.positive.coverage).toEqual({
         frames: entry.positive.coverage.frames,

package/src/__tests__/nineslice-handle-surface.unit.test.ts

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs';
 
 import { describe, expect, it } from 'vitest';
 
-const frameSource = readFileSync(new URL('../record/frame.ts', import.meta.url), 'utf8');
+const foldSource = readFileSync(new URL('../record/fold-buckets.ts', import.meta.url), 'utf8');
 const materialSource = readFileSync(
   new URL('../record/main-pass-material.ts', import.meta.url),
   'utf8',
@@ -10,9 +10,9 @@ const materialSource = readFileSync(
 
 describe('9-slice handle ownership', () => {
   it('derives the lookup key from the canonical asset-runtime handle', () => {
-    expect(frameSource).toContain('handleSlot(HANDLE_NINESLICE_QUAD)');
-    expect(frameSource).toContain('r.assetHandle > handleSlot(HANDLE_NINESLICE_QUAD)');
-    expect(frameSource).not.toMatch(/BUILTIN_MESH_ID_MAX/);
+    expect(foldSource).toContain('handleSlot(HANDLE_NINESLICE_QUAD)');
+    expect(foldSource).toContain('r.assetHandle > handleSlot(HANDLE_NINESLICE_QUAD)');
+    expect(foldSource).not.toMatch(/BUILTIN_MESH_ID_MAX/);
     expect(materialSource).not.toMatch(/NINESLICE_QUAD_RAW_ID\s*=/);
     expect(materialSource).not.toMatch(/BUILTIN_MESH_ID_MAX\s*=/);
   });

package/src/__tests__/pbr-view-layout.unit.test.ts

@@ -13,4 +13,13 @@ describe('PBR view bind-group layout', () => {
         .map((entry) => entry.binding),
     ).toEqual([0, 10]);
   });
+
+  it('omits cloud shadow bindings on the minimum sampled-texture profile', () => {
+    const entries = buildPbrViewBglEntries({
+      storageBuffer: true,
+      extendedLighting: false,
+      projectorAvailable: false,
+    });
+    expect(entries.some((entry) => entry.binding === 16 || entry.binding === 17)).toBe(false);
+  });
 });

package/src/__tests__/physical-clearcoat.integration.test.ts

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { STANDARD_PIPELINE_PARAM_SCHEMA } from '@forgeax/engine-shader';
 import { describe, expect, it } from 'vitest';
 import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from '../gpu-stage.js';
@@ -125,4 +127,60 @@ describe('Standard clearcoat root contract', () => {
       47,
     ]);
   });
+
+  it('derives the single-layer medium depth and nearest inputs at the shader bindings', () => {
+    const descriptor = buildBindGroupLayoutDescriptor(
+      {
+        shader: {
+          id: 'forgeax::single-layer-medium',
+          passKind: 'forward',
+          variantSet: undefined,
+        },
+        attachments: { colorFormats: [], depthFormat: undefined, sampleCount: 1 },
+        geometry: { topology: 'triangle-list', vertexLayout: {} },
+        renderState: undefined,
+      },
+      { kind: 'pbr-material-merged', materialParamSchema: [] },
+    );
+
+    expect(descriptor.entries.map((entry) => entry.binding)).toEqual([
+      ...Array.from({ length: 16 }, (_, binding) => binding),
+      46,
+    ]);
+    expect(descriptor.entries[10]).toMatchObject({
+      sampler: { type: 'non-filtering' },
+    });
+    expect(descriptor.entries[11]).toMatchObject({
+      texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+    });
+    expect(descriptor.entries[12]).toMatchObject({
+      sampler: { type: 'filtering' },
+    });
+    expect(descriptor.entries[13]).toMatchObject({
+      texture: { sampleType: 'float', viewDimension: '2d' },
+    });
+    expect(descriptor.entries[14]).toMatchObject({
+      sampler: { type: 'non-filtering' },
+    });
+    expect(descriptor.entries[15]).toMatchObject({
+      texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+    });
+
+    // The medium is a project material artifact with an explicit empty
+    // paramSchema. Its per-shader user region is therefore the reserved UBO
+    // at binding 0, followed by IBL 1..7, transmission 8..9, and Surface
+    // resources 10..15. Keep this source assertion next to the descriptor
+    // assertion so a future injection-order change cannot leave a compiled
+    // WGSL binding map out of sync with the runtime BGL.
+    const source = readFileSync(
+      resolve(import.meta.dirname, '../../../shader/src/single-layer-medium.wgsl'),
+      'utf8',
+    );
+    expect(source).toContain('@group(1) @binding(10) var surfaceRawDepthSampler');
+    expect(source).toContain('@group(1) @binding(11) var surfaceRawDepthTexture');
+    expect(source).toContain('@group(1) @binding(12) var surfaceNearestLayerSampler');
+    expect(source).toContain('@group(1) @binding(13) var surfaceNearestLayerTexture');
+    expect(source).toContain('@group(1) @binding(14) var surfaceNearestDepthSampler');
+    expect(source).toContain('@group(1) @binding(15) var surfaceNearestDepthTexture');
+  });
 });

package/src/__tests__/prepared-graphics-capability.unit.test.ts

@@ -25,6 +25,31 @@ function preparedFeature(): RenderFeature<{ readonly draw: boolean }> {
   };
 }
 
+function activePreparedFeature(
+  active: () => boolean = () => true,
+): RenderFeature<{ readonly draw: boolean }> {
+  return {
+    identity: 'synthetic.capability.active',
+    requiredCapabilities: ['compute'],
+    extract: () => ok({ draw: active() }),
+    plan: ({ draw }) =>
+      ok(
+        draw
+          ? {
+              resources: [
+                {
+                  kind: 'fullscreen-program' as const,
+                  name: 'synthetic.capability.program',
+                  source: 'synthetic',
+                },
+              ],
+              passes: [],
+            }
+          : { resources: [], passes: [] },
+      ),
+  };
+}
+
 describe('prepared graphics capability projection', () => {
   it('keeps LUT filtering as an independent live capability', () => {
     const result = admitStandardColorLut({
@@ -61,7 +86,7 @@ describe('prepared graphics capability projection', () => {
     expect(host.diagnostics()[0]?.status).toBe('active');
   });
 
-  it('returns a structured capability failure without a silent operation', () => {
+  it('does not admit an inactive empty plan on an unsupported backend', () => {
     const host = createRenderFeatureHost([preparedFeature()]).unwrap();
     const result = runRenderFeatureFrame(host, {
       worlds: [],
@@ -70,6 +95,21 @@ describe('prepared graphics capability projection', () => {
       caps: missingCaps,
     });
 
+    expect(result.errors).toEqual([]);
+    expect(result.preparedResourceBatches).toHaveLength(0);
+    expect(result.plans[0]?.plan).toEqual({ resources: [], passes: [] });
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
+
+  it('returns a structured capability failure without a silent operation', () => {
+    const host = createRenderFeatureHost([activePreparedFeature()]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: missingCaps,
+    });
+
     expect(result.plans).toEqual([]);
     expect(result.errors).toHaveLength(1);
     expect(result.errors[0]).toMatchObject({
@@ -77,10 +117,34 @@ describe('prepared graphics capability projection', () => {
       expected: expect.stringContaining('compute'),
       hint: expect.stringContaining('disable'),
       detail: {
-        featureIdentity: 'synthetic.capability',
+        featureIdentity: 'synthetic.capability.active',
         capability: 'compute',
       },
     });
     expect(host.diagnostics()[0]?.status).toBe('disabled');
   });
+
+  it('lets an active capability failure recover when the authored plan is disabled', () => {
+    let enabled = true;
+    const host = createRenderFeatureHost([activePreparedFeature(() => enabled)]).unwrap();
+    const failed = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps: missingCaps,
+    });
+    expect(failed.errors.map((error) => error.code)).toEqual(['render-feature-capability-missing']);
+    expect(host.diagnostics()[0]?.status).toBe('disabled');
+
+    enabled = false;
+    const recovered = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 2,
+      caps: missingCaps,
+    });
+    expect(recovered.errors).toEqual([]);
+    expect(recovered.plans[0]?.plan).toEqual({ resources: [], passes: [] });
+    expect(host.diagnostics()[0]?.status).toBe('active');
+  });
 });