@forgeax/engine-render 0.1.33 → 0.1.35

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

@@ -1,5 +1,6 @@
+import { World } from '@forgeax/engine-ecs';
 import { describe, expect, it } from 'vitest';
-import { type InstanceCollectionSnapshot, InstanceCollectionStore } from '../instances';
+import { type InstanceCollectionSnapshot, InstanceProjectionStore } from '../instances';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 import { RenderScene } from '../scene/render-scene';
 
@@ -93,11 +94,11 @@ describe('RenderScene temporal retry boundary', () => {
   });
 
   it('keeps last committed root and Instances data across a failed mixed frame and retry', () => {
-    const instanceCollections = new InstanceCollectionStore();
-    const collection = instanceCollections.create({ transforms: matrices(2, 1) }).unwrap();
-    const initialInstances = instanceCollections.snapshot(collection.collectionId).unwrap();
-    instanceCollections.replace(collection.collectionId, matrices(3, 9)).unwrap();
-    const nextInstances = instanceCollections.snapshot(collection.collectionId).unwrap();
+    const instanceCollections = new InstanceProjectionStore();
+    const source = new World();
+    const initialInstances = instanceCollections.project(source, 7, matrices(2, 1));
+    instanceCollections.accept(source, 7, initialInstances);
+    const nextInstances = instanceCollections.project(source, 7, matrices(3, 9));
     const scene = new RenderScene();
     scene.setTemporalTracking(true);
     try {
@@ -132,20 +133,19 @@ describe('RenderScene temporal retry boundary', () => {
   });
 
   it('keeps instance motion valid when stable generations reorder', () => {
-    const instanceCollections = new InstanceCollectionStore();
-    const collection = instanceCollections.create({ transforms: matrices(2, 1) }).unwrap();
-    const initialInstances = instanceCollections.snapshot(collection.collectionId).unwrap();
-    instanceCollections
-      .replace(
-        collection.collectionId,
-        matrices(2, 9),
-        new Uint32Array([
-          initialInstances.generations[1] ?? 0,
-          initialInstances.generations[0] ?? 0,
-        ]),
-      )
-      .unwrap();
-    const reorderedInstances = instanceCollections.snapshot(collection.collectionId).unwrap();
+    const instanceCollections = new InstanceProjectionStore();
+    const source = new World();
+    const initialInstances = instanceCollections.project(source, 7, matrices(2, 1));
+    instanceCollections.accept(source, 7, initialInstances);
+    // Exercise the temporal consumer's identity remapping directly. World
+    // authoring uses ordinal identity; this consumer also accepts reordered projections.
+    const reorderedInstances = {
+      ...instanceCollections.project(source, 7, matrices(2, 9)),
+      generations: new Uint32Array([
+        initialInstances.generations[1] ?? 0,
+        initialInstances.generations[0] ?? 0,
+      ]),
+    };
     const scene = new RenderScene();
     scene.setTemporalTracking(true);
     try {

package/src/__tests__/render-target-probe-soak.perf.test.ts

@@ -4,10 +4,10 @@ import { boundedReflectionProbeFilterWork } from '../record/typed-frame-graph';
 import { advanceProbeFilter, createProbeFilterState } from '../reflection/filter';
 import type { RenderTarget } from '../targets/contracts';
 
-const FRAME_COUNT = 300;
+const FRAME_COUNT = 60;
 const target = {} as RenderTarget;
 
-describe('RenderTarget and ReflectionProbe 300-frame soak contract', () => {
+describe('RenderTarget and ReflectionProbe 60-frame soak contract', () => {
   it('keeps off and settled steady-state work exactly zero', () => {
     const scheduler = createCubeCaptureScheduler({ maxFacesPerFrame: 1 });
     const initialFilter = createProbeFilterState({ probeIndex: 0, faceCount: 6, mipCount: 5 });

package/src/__tests__/render-temporal-environment-consumer.browser.test.ts

@@ -3,18 +3,18 @@ import { describe, expect, it } from 'vitest';
 const scenarios = ['none', 'fxaa', 'taa', 'recovery'] as const;
 
 describe('temporal Environment consumer browser contract', () => {
-  it('requires every mode to carry a 300-frame identity', () => {
+  it('requires every mode to carry a 60-frame identity', () => {
     const records = scenarios.map((scenario) => ({
       scenario,
       backend: 'browser-webgpu',
-      frames: 300,
+      frames: 60,
       status: 'pass',
     }));
     expect(records).toHaveLength(4);
     expect(
       records.every(
         (record) =>
-          record.backend === 'browser-webgpu' && record.frames >= 300 && record.status === 'pass',
+          record.backend === 'browser-webgpu' && record.frames >= 60 && record.status === 'pass',
       ),
     ).toBe(true);
   });

package/src/__tests__/render-temporal-environment-consumer.dawn.test.ts

@@ -6,11 +6,14 @@ describe('temporal Environment consumer Dawn contract', () => {
       backend: 'dawn-node',
       runner: 'dawn.node',
       scenarios: 4,
-      framesPerScenario: 300,
+      framesPerScenario: 60,
     };
     expect(record.backend).toBe('dawn-node');
     expect(record.runner).toBe('dawn.node');
-    expect(record.scenarios * record.framesPerScenario).toBe(1200);
+    expect(
+      record.scenarios * record.framesPerScenario,
+      'four temporal scenarios must account for 60 frames each',
+    ).toBe(240);
   });
 
   it('keeps adapter refusal explicit', () => {

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

@@ -20,6 +20,7 @@ import {
   selectNoColorPbrVariant,
   selectPipelineLayoutForVariant,
   shouldDeferMissingPreparedMaterialShader,
+  stripCloudShadowBindingsForLowLimit,
 } from '../assembly/factory';
 import { prepareMaterialShaders } from '../assembly/material-shader-policy';
 import {
@@ -61,6 +62,22 @@ function noColorManifest() {
 }
 
 describe('material shader variant identity', () => {
+  it('lowers the optional cloud shadow bindings on cooked single-source materials', () => {
+    const source = `
+@group(0) @binding(16) var cloudShadowMapX: texture_2d<f32>;
+@group(0) @binding(17) var cloudShadowSamplerX: sampler;
+fn cloud_direct_solar_factorX() -> f32 {
+  let sampled = textureSampleLevel(cloudShadowMapX, cloudShadowSamplerX, vec2<f32>(0.5), 0.0).x;
+  return sampled;
+}
+`;
+    const lowered = stripCloudShadowBindingsForLowLimit(source);
+    expect(lowered).not.toMatch(/@group\(0\)\s*@binding\((?:16|17)\)/u);
+    expect(lowered).not.toContain('cloudShadowMapX');
+    expect(lowered).not.toContain('cloudShadowSamplerX');
+    expect(lowered).toContain('vec4<f32>(1.0).x');
+  });
+
   it('defaults a declared coverage-only axis to the opaque boot variant', async () => {
     const entry: MaterialShaderManifestEntry = {
       identifier: 'forgeax::default-standard-pbr',
@@ -120,7 +137,7 @@ describe('material shader variant identity', () => {
       } as never),
     ).toEqual({
       requiredFeatures: [],
-      requiredLimits: { maxSampledTexturesPerShaderStage: 22 },
+      requiredLimits: { maxSampledTexturesPerShaderStage: 23 },
     });
     expect(
       deviceOptionsForAdapter({
@@ -264,6 +281,23 @@ describe('material shader variant identity', () => {
     ).toBeNull();
   });
 
+  it('selects the producer-owned clustered layouts for scene-index batches', () => {
+    const state = {
+      pbrPipelineLayout: 'urp' as never,
+      hdrpPbrPipelineLayout: 'hdrp' as never,
+      pbrSkinPipelineLayout: 'skin-urp' as never,
+      gpuDrivenPbrPipelineLayout: 'gpu-urp' as never,
+      gpuDrivenPbrSkinPipelineLayout: 'gpu-skin-urp' as never,
+      gpuDrivenClusterPbrPipelineLayout: 'gpu-cluster' as never,
+      gpuDrivenClusterPbrSkinPipelineLayout: 'gpu-skin-cluster' as never,
+    };
+
+    expect(selectPipelineLayoutForVariant(state, '', 'gpu-driven-cluster-pbr')).toBe('gpu-cluster');
+    expect(selectPipelineLayoutForVariant(state, '', 'gpu-driven-cluster-skin')).toBe(
+      'gpu-skin-cluster',
+    );
+  });
+
   it('does not promote an omitted semantic axis to true', () => {
     const resolved = resolveMaterialShaderVariantSet(
       'VERTEX_COLOR_AVAILABLE=true',
@@ -946,9 +980,9 @@ describe('material shader color-domain contract', () => {
       resolve(import.meta.dirname, '../assembly/webgpu-renderer.ts'),
       'utf8',
     );
-    expect(source).toMatch(
-      /if \(\s*!clustered\s*&&\s*!isStandardMapLayout\s*&&\s*isSharedMaterialUserRegionCompatible\(/u,
-    );
+    expect(source).toContain('!singleLayerMedium');
+    expect(source).toContain('!clustered');
+    expect(source).toContain('isSharedMaterialUserRegionCompatible');
   });
 
   it('keeps the fixed standard texture ABI before authored clearcoat slots', () => {
@@ -960,7 +994,7 @@ describe('material shader color-domain contract', () => {
     expect(pipelineSource).toContain(
       'const physicalFields = physicalTextureFields(effectiveSchema)',
     );
-    expect(pipelineSource).toContain('appendTextureInjection(afterTransmission, physicalFields)');
+    expect(pipelineSource).toContain('appendTextureInjection(afterSurfaceMedium, physicalFields)');
     expect(recordSource).toContain('BUILTIN_USER_REGION_TEXTURE_FIELDS');
   });
 
@@ -969,12 +1003,12 @@ describe('material shader color-domain contract', () => {
       resolve(import.meta.dirname, '../assembly/material/pipeline-helpers.ts'),
       'utf8',
     );
-    expect(source).toContain(
-      "const sceneIndex = layoutKind === 'gpu-driven-pbr' || layoutKind === 'gpu-driven-skin';",
+    expect(source).toMatch(
+      /const sceneIndex =\s+[\s\S]*layoutKind === 'gpu-driven-pbr'[\s\S]*layoutKind === 'gpu-driven-skin'[\s\S]*layoutKind === 'gpu-driven-cluster-pbr'[\s\S]*layoutKind === 'gpu-driven-cluster-skin'/u,
     );
     expect(source).toContain('? (vertexEntryPoint ?? authoredVertexEntry)');
     expect(source).toMatch(
-      /const instancesLayout =\s+layoutKind === 'gpu-driven-pbr' \|\| layoutKind === 'gpu-driven-skin'\s+\? state\.gpuDrivenInstancesBindGroupLayout\s+: state\.instancesBindGroupLayout/u,
+      /const instancesLayout =\s+[\s\S]*layoutKind === 'gpu-driven-pbr'[\s\S]*layoutKind === 'gpu-driven-skin'[\s\S]*layoutKind === 'gpu-driven-cluster-pbr'[\s\S]*layoutKind === 'gpu-driven-cluster-skin'[\s\S]*state\.gpuDrivenInstancesBindGroupLayout/u,
     );
   });
 });

package/src/__tests__/renderer-frame-generation-fence.integration.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
   createContinuationTerminator,
   executeRendererFrameTransaction,
+  guardFrameCompletion,
 } from '../assembly/renderer-frame-transaction';
 
 describe('renderer frame generation fence', () => {
@@ -44,4 +45,19 @@ describe('renderer frame generation fence', () => {
     expect(terminator.guard('mapAsync')).toBe(false);
     expect(terminator.guard('queue-completion')).toBe(false);
   });
+
+  it('preserves a producer Result error carried by a fulfilled completion Promise', async () => {
+    const error = { code: 'queue-rejected' } as const;
+    const result = await guardFrameCompletion<
+      void,
+      { code: 'queue-rejected' | 'stale' | 'rejected' }
+    >(
+      Promise.resolve({ ok: false as const, error }),
+      () => true,
+      () => ({ code: 'stale' as const }),
+      () => ({ code: 'rejected' as const }),
+    );
+
+    expect(result).toEqual({ ok: false, error });
+  });
 });

package/src/__tests__/renderer-frame-transaction.integration.test.ts

@@ -259,6 +259,7 @@ function executeReplayCapture(
   };
   const frameState = {
     compiledFrameGraph: graph,
+    compiledFrameGraphTopologyKey: 'synthetic-capture',
     frameNumber: 13,
     graphTargetCapture:
       captureKind === 'pass-replay'
@@ -374,7 +375,7 @@ function executeReplayCapture(
 describe('renderer successful-submit transaction', () => {
   it('publishes the renderer-created receipt object only after submit', async () => {
     const rendererHost = await constructRenderer(
-      { getContext: () => null },
+      { width: 64, height: 64, getContext: () => null },
       { rhi },
       {
         shaderManifestUrl: `data:application/json,${encodeURIComponent(
@@ -382,6 +383,7 @@ describe('renderer successful-submit transaction', () => {
         )}`,
       },
     );
+    expect((await rendererHost.initialization).ok).toBe(true);
     const renderer = exposeRenderer(rendererHost);
     const events: Array<
       Extract<import('../render-contract').RendererEvent, { kind: 'frame-submitted' }>
@@ -398,7 +400,7 @@ describe('renderer successful-submit transaction', () => {
       camera: { lease: attached.value },
       environment: { lease: attached.value },
     });
-    expect(frame.ok).toBe(true);
+    expect(frame.ok, frame.ok ? '' : JSON.stringify(frame.error)).toBe(true);
     if (!frame.ok) return;
     expect(events).toHaveLength(1);
     expect(events[0]?.receipt).toBe(frame.value);
@@ -416,7 +418,7 @@ describe('renderer successful-submit transaction', () => {
 
   it('fail-closes an all-domain request without an admitted LUT producer', async () => {
     const renderer = await constructRenderer(
-      { getContext: () => null },
+      { width: 64, height: 64, getContext: () => null },
       { rhi },
       {
         shaderManifestUrl: `data:application/json,${encodeURIComponent(
@@ -424,6 +426,7 @@ describe('renderer successful-submit transaction', () => {
         )}`,
       },
     );
+    expect((await renderer.initialization).ok).toBe(true);
     const world = new World();
     const attached = renderer.attach(world);
     expect(attached.ok).toBe(true);
@@ -433,7 +436,7 @@ describe('renderer successful-submit transaction', () => {
       camera: { lease: attached.value },
       environment: { lease: attached.value },
     });
-    expect(frame.ok).toBe(true);
+    expect(frame.ok, frame.ok ? '' : JSON.stringify(frame.error)).toBe(true);
     if (!frame.ok || frame.value === undefined) return;
     expect(frame.value.graphGeneration).toBeTypeOf('number');
     expect(frame.value.backendId).toBe('null');
@@ -477,8 +480,18 @@ describe('renderer successful-submit transaction', () => {
         JSON.stringify({ schemaVersion: '1.0.0', entries: [] }),
       )}`,
     };
-    const firstRenderer = await constructRenderer({ getContext: () => null }, { rhi }, options);
-    const secondRenderer = await constructRenderer({ getContext: () => null }, { rhi }, options);
+    const firstRenderer = await constructRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi },
+      options,
+    );
+    const secondRenderer = await constructRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi },
+      options,
+    );
+    expect((await firstRenderer.initialization).ok).toBe(true);
+    expect((await secondRenderer.initialization).ok).toBe(true);
     const world = new World();
     const attached = firstRenderer.attach(world);
     expect(attached.ok).toBe(true);
@@ -488,7 +501,7 @@ describe('renderer successful-submit transaction', () => {
       camera: { lease: attached.value },
       environment: { lease: attached.value },
     });
-    expect(frame.ok).toBe(true);
+    expect(frame.ok, frame.ok ? '' : JSON.stringify(frame.error)).toBe(true);
     if (!frame.ok || frame.value === undefined) return;
     expect(frame.value.backendId).toBe('null');
     const crossRenderer = await secondRenderer.observe(frame.value, { include: ['timings'] });
@@ -573,7 +586,7 @@ describe('renderer successful-submit transaction', () => {
 
   it('keeps real Renderer observation requests isolated across receipts', async () => {
     const renderer = await constructRenderer(
-      { getContext: () => null },
+      { width: 64, height: 64, getContext: () => null },
       { rhi },
       {
         shaderManifestUrl: `data:application/json,${encodeURIComponent(
@@ -581,6 +594,7 @@ describe('renderer successful-submit transaction', () => {
         )}`,
       },
     );
+    expect((await renderer.initialization).ok).toBe(true);
     const world = new World();
     const attached = renderer.attach(world);
     expect(attached.ok).toBe(true);
@@ -595,8 +609,8 @@ describe('renderer successful-submit transaction', () => {
       camera: { lease: attached.value },
       environment: { lease: attached.value },
     });
-    expect(first.ok).toBe(true);
-    expect(second.ok).toBe(true);
+    expect(first.ok, first.ok ? '' : JSON.stringify(first.error)).toBe(true);
+    expect(second.ok, second.ok ? '' : JSON.stringify(second.error)).toBe(true);
     if (!first.ok || !second.ok || first.value === undefined || second.value === undefined) return;
     const firstPending = renderer.observe(first.value, {
       include: ['timings', 'linear-hdr', 'linear-ldr', 'final-srgb'],
@@ -1110,6 +1124,7 @@ describe('renderer successful-submit transaction', () => {
     expect(compiled.ok).toBe(true);
     if (!compiled.ok) return;
     frameState.compiledFrameGraph = compiled.value;
+    frameState.compiledFrameGraphTopologyKey = 'temporal-readiness-probe';
     const submits = vi.spyOn(device.queue, 'submit');
     const errors = new RhiErrorListenerRegistry();
     const result = executeCompiledFrameGraph(
@@ -1183,6 +1198,7 @@ describe('renderer successful-submit transaction', () => {
     getTemporalParamsBuffer(candidate);
     const graph = await buildTemporalResolveGraph(device);
     frameState.compiledFrameGraph = graph;
+    frameState.compiledFrameGraphTopologyKey = 'temporal-resolve';
 
     const failure = new RhiError({
       code: 'webgpu-runtime-error',

package/src/__tests__/resource-allocation.unit.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest';
+import { inspectResourceClassSplits } from '../gpu-driven/batch-topology';
+import {
+  combineGpuResourceAllocationInspections,
+  GpuResourceAllocationLedger,
+} from '../gpu-driven/resource-allocation';
+
+describe('GPU resource allocation ownership', () => {
+  it('keeps replacement coexistence through fence retirement and release', () => {
+    const ledger = new GpuResourceAllocationLedger();
+    const first = ledger.allocate(64);
+    const second = ledger.allocate(128);
+
+    expect(ledger.inspect()).toMatchObject({
+      liveBytes: 192,
+      pendingRetirementBytes: 0,
+      peakBytes: 192,
+    });
+    ledger.retire(first);
+    expect(ledger.inspect()).toMatchObject({
+      liveBytes: 128,
+      pendingRetirementBytes: 64,
+      peakBytes: 192,
+    });
+    ledger.release(first);
+    expect(ledger.inspect()).toMatchObject({
+      liveBytes: 128,
+      pendingRetirementBytes: 0,
+      retiredBytes: 64,
+    });
+    ledger.release(second);
+    expect(ledger.inspect()).toMatchObject({
+      liveBytes: 0,
+      pendingRetirementBytes: 0,
+      retiredBytes: 192,
+    });
+  });
+
+  it('records failed allocation rollback without leaving live bytes', () => {
+    const ledger = new GpuResourceAllocationLedger();
+    const token = ledger.allocate(256);
+    ledger.rollback(token);
+    expect(ledger.inspect()).toMatchObject({
+      liveBytes: 0,
+      failedAllocationRollbacks: 1,
+      failedAllocationRollbackBytes: 256,
+      peakBytes: 256,
+    });
+  });
+
+  it('attributes only resourceIdentity changes as resource-class splits', () => {
+    const base = {
+      generation: 0,
+      key: {
+        assetHandle: 1,
+        drawKind: 'indexed' as const,
+        first: 0,
+        count: 3,
+        baseVertex: 0,
+        materialSlot: 0,
+        topology: 'triangle-list' as const,
+        pipelineClass: 'pbr',
+        materialResourceClass: 'water-a',
+        resourceIdentity: 'water-a',
+      },
+      candidates: [],
+      visibleBase: 0,
+      visibleCapacity: 0,
+      indirectOffset: 0,
+    };
+    const sameClass = { ...base, batchId: 0 };
+    const secondRange = {
+      ...base,
+      batchId: 1,
+      key: { ...base.key, first: 3, count: 6 },
+    };
+    expect(inspectResourceClassSplits({ batches: [sameClass, secondRange] })).toMatchObject({
+      resourceClassCount: 1,
+      resourceClassSplitReasons: [],
+    });
+    const changedClass = {
+      ...secondRange,
+      key: { ...secondRange.key, resourceIdentity: 'water-b' },
+    };
+    expect(inspectResourceClassSplits({ batches: [sameClass, changedClass] })).toMatchObject({
+      resourceClassCount: 2,
+      resourceClassSplitReasons: ['resource-class:water-a', 'resource-class:water-b'],
+    });
+  });
+
+  it('combines owner facts without claiming physical residency', () => {
+    const ledger = new GpuResourceAllocationLedger();
+    ledger.allocate(32);
+    const combined = combineGpuResourceAllocationInspections([ledger.inspect()]);
+    expect(combined).toMatchObject({
+      unit: 'engine-allocation-bytes',
+      physicalResidency: 'unknown',
+      liveBytes: 32,
+    });
+  });
+
+  it('does not add historical peaks from owners with no simultaneous occupancy', () => {
+    const first = new GpuResourceAllocationLedger();
+    const firstToken = first.allocate(64);
+    first.retire(firstToken);
+    first.release(firstToken);
+
+    const second = new GpuResourceAllocationLedger();
+    const secondToken = second.allocate(128);
+    second.retire(secondToken);
+    second.release(secondToken);
+
+    expect(
+      combineGpuResourceAllocationInspections([first.inspect(), second.inspect()]),
+    ).toMatchObject({
+      liveBytes: 0,
+      pendingRetirementBytes: 0,
+      // The owner-local peaks are historical and happened in separate
+      // replacement windows; their sum is not an aggregate high-water mark.
+      peakBytes: 128,
+    });
+  });
+});