@forgeax/engine-runtime 0.1.19 → 0.1.21

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

@@ -31,9 +31,8 @@
 //   - packages/runtime/src/__tests__/render-data.test.ts
 //   - packages/runtime/src/__tests__/hdrp-bgl-slots.test.ts
 //   - packages/runtime/src/__tests__/hdrp-caps-gate.test.ts
-//   - packages/runtime/src/__tests__/hdrp-grid-invalid.test.ts
-//   - packages/runtime/src/__tests__/hdrp-index-list-overflow-once.test.ts
-//   - packages/runtime/src/__tests__/hdrp-light-budget.test.ts
+//   - packages/runtime/src/__tests__/standard-profile-invalid.test.ts
+//   - packages/runtime/src/__tests__/standard-cluster-index-overflow-once.test.ts
 //   - packages/runtime/src/__tests__/hdrp-pipeline-asset-config.test.ts
 //   - packages/runtime/src/__tests__/m7-hdrp-demo-shape.test.ts
 //
@@ -110,16 +109,14 @@ import {
 } from '../../../render/src/cluster-binner';
 import { GpuResidencyCache } from '../../../render/src/device/gpu-residency';
 import { createEngineMetrics } from '../../../render/src/engine-metrics';
+import { StandardProfileInvalidError } from '../../../render/src/errors/render';
 import { assertStorageBufferCap } from '../../../render/src/light-buffer-layout';
 import {
   buildPbrPipelineLayouts,
   buildPbrViewBglEntries,
   type PbrCaps,
 } from '../../../render/src/pbr-pipeline';
-import {
-  HdrpInstallError,
-  validateClusterGrid,
-} from '../../../render/src/pipeline/standard-pipeline';
+import { validateClusterGrid } from '../../../render/src/pipeline/standard-pipeline';
 import {
   buildPipelineForMaterialShader,
   type PipelineBuilderContext,
@@ -2122,13 +2119,13 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
     // sprite; the test locks the outcome so an inline-logic drift is caught.
     function resolveBootDefinesKey(
       msEntry: MaterialShaderManifestEntry,
-      opts: { readonly storageBufferCapable: boolean; readonly isHdrpActive: boolean },
+      opts: { readonly storageBufferCapable: boolean; readonly clusteredLighting: boolean },
     ): string {
       const variantDefines: Record<string, boolean> = {
         STORAGE_BUFFER_AVAILABLE: opts.storageBufferCapable,
       };
       if (msEntry.variants.some((v) => 'CLUSTER_FORWARD_AVAILABLE' in v.defines)) {
-        variantDefines.CLUSTER_FORWARD_AVAILABLE = opts.isHdrpActive;
+        variantDefines.CLUSTER_FORWARD_AVAILABLE = opts.clusteredLighting;
       }
       if (msEntry.variants.some((v) => 'PER_INSTANCE_REGION' in v.defines)) {
         variantDefines.PER_INSTANCE_REGION = false;
@@ -2145,7 +2142,7 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
       const spriteEntry = makeSpriteEntry();
       const definesKey = resolveBootDefinesKey(spriteEntry, {
         storageBufferCapable: true,
-        isHdrpActive: false,
+        clusteredLighting: false,
       });
       expect(definesKey).toBe('PER_INSTANCE_REGION=false+STORAGE_BUFFER_AVAILABLE=true');
       const variant = findVariantByKey(spriteEntry, definesKey);
@@ -2162,7 +2159,7 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
       const spriteEntry = makeSpriteEntry();
       const definesKey = resolveBootDefinesKey(spriteEntry, {
         storageBufferCapable: false,
-        isHdrpActive: false,
+        clusteredLighting: false,
       });
       expect(definesKey).toBe('PER_INSTANCE_REGION=false+STORAGE_BUFFER_AVAILABLE=false');
       const variant = findVariantByKey(spriteEntry, definesKey);
@@ -2197,7 +2194,7 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
       const spriteEntry = makeSpriteEntry();
       const bootDefinesKey = resolveBootDefinesKey(spriteEntry, {
         storageBufferCapable: true,
-        isHdrpActive: false,
+        clusteredLighting: false,
       });
       const bootVariant = findVariantByKey(spriteEntry, bootDefinesKey);
       const spriteInstancesVariant = findVariantByKey(spriteEntry, '');
@@ -4466,12 +4463,11 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
   function texturePod(mipmap: boolean, format: GPUTextureFormat = 'rgba8unorm-srgb'): TextureAsset {
     return {
       kind: 'texture',
-      width: 2,
-      height: 2,
+      shape: { viewDimension: '2d', extent: { width: 2, height: 2 } },
       format,
       data: new Uint8Array(2 * 2 * 4).fill(188),
       colorSpace: format.endsWith('-srgb') ? 'srgb' : 'linear',
-      mipmap,
+      mips: { kind: mipmap ? 'generate' : 'none' },
     };
   }
 
@@ -4549,12 +4545,11 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
   ): TextureAsset {
     return {
       kind: 'texture',
-      width,
-      height,
+      shape: { viewDimension: '2d', extent: { width, height } },
       format,
       data: new Uint8Array(width * height * 4).fill(170),
       colorSpace: format.endsWith('-srgb') ? 'srgb' : 'linear',
-      mipmap,
+      mips: { kind: mipmap ? 'generate' : 'none' },
     };
   }
 
@@ -4566,12 +4561,11 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
   ): TextureAsset {
     return {
       kind: 'texture',
-      width,
-      height,
+      shape: { viewDimension: '2d', extent: { width, height } },
       format,
       data: new Uint8Array(width * height * 8),
       colorSpace,
-      mipmap: false,
+      mips: { kind: 'none' },
     };
   }
 
@@ -4658,33 +4652,35 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
       const source = texturePod(false, 'rgba16float');
       const res = deriveRenderDataTexture({
         ...source,
-        data: new Uint8Array(source.width * source.height * 8),
+        data: new Uint8Array(source.shape.extent.width * source.shape.extent.height * 8),
       });
       expect(res.ok).toBe(true);
       if (!res.ok) return;
-      expect(res.value.bytesPerRow).toBe(source.width * 8);
+      expect(res.value.bytesPerRow).toBe(source.shape.extent.width * 8);
     });
 
     it('derives row pitch from format when an rgba8 decoder retains trailing bytes', () => {
       const source = texturePod(false, 'rgba8unorm');
       const res = deriveRenderDataTexture({
         ...source,
-        data: new Uint8Array(source.width * source.height * 4 + source.width),
+        data: new Uint8Array(
+          source.shape.extent.width * source.shape.extent.height * 4 + source.shape.extent.width,
+        ),
       });
       expect(res.ok).toBe(true);
       if (!res.ok) return;
-      expect(res.value.bytesPerRow).toBe(source.width * 4);
+      expect(res.value.bytesPerRow).toBe(source.shape.extent.width * 4);
     });
 
     it('derives the row pitch from an rgba32float source payload', () => {
       const source = texturePod(false, 'rgba32float');
       const res = deriveRenderDataTexture({
         ...source,
-        data: new Uint8Array(source.width * source.height * 16),
+        data: new Uint8Array(source.shape.extent.width * source.shape.extent.height * 16),
       });
       expect(res.ok).toBe(true);
       if (!res.ok) return;
-      expect(res.value.bytesPerRow).toBe(source.width * 16);
+      expect(res.value.bytesPerRow).toBe(source.shape.extent.width * 16);
     });
 
     it('rejects an uncompressed payload shorter than its base mip', () => {
@@ -4935,40 +4931,49 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
 }
 
 {
-  // --- from hdrp-grid-invalid.test.ts ---
-  describe('hdrp-grid-invalid', () => {
+  // --- from standard-profile-invalid.test.ts ---
+  describe('standard-profile-invalid', () => {
     describe('validateClusterGrid', () => {
       // AC-23 scenario (a): x === 0
-      it('rejects x=0 with code hdrp-grid-invalid and hint contains "positive integer"', () => {
+      it('rejects x=0 with code standard-profile-invalid and hint contains "positive integer"', () => {
         const result = validateClusterGrid({ x: 0, y: 9, z: 24 });
         expect(result.ok).toBe(false);
         if (!result.ok) {
-          expect(result.error.code).toBe('hdrp-grid-invalid');
+          expect(result.error.code).toBe('standard-profile-invalid');
           expect(result.error.hint).toContain('positive integer');
           expect(result.error.expected).toContain('[1, 64]');
-          expect(result.error.detail).toEqual({ x: 0, y: 9, z: 24 });
+          expect(result.error.detail).toEqual({
+            field: 'clusterGrid',
+            actual: { x: 0, y: 9, z: 24 },
+          });
         }
       });
 
       // AC-23 scenario (b): non-integer x=1.5
-      it('rejects x=1.5 (non-integer) with code hdrp-grid-invalid', () => {
+      it('rejects x=1.5 (non-integer) with code standard-profile-invalid', () => {
         const result = validateClusterGrid({ x: 1.5, y: 9, z: 24 });
         expect(result.ok).toBe(false);
         if (!result.ok) {
-          expect(result.error.code).toBe('hdrp-grid-invalid');
+          expect(result.error.code).toBe('standard-profile-invalid');
           expect(result.error.hint).toContain('positive integer');
-          expect(result.error.detail).toEqual({ x: 1.5, y: 9, z: 24 });
+          expect(result.error.detail).toEqual({
+            field: 'clusterGrid',
+            actual: { x: 1.5, y: 9, z: 24 },
+          });
         }
       });
 
       // AC-23 scenario (c): y === -1
-      it('rejects y=-1 with code hdrp-grid-invalid', () => {
+      it('rejects y=-1 with code standard-profile-invalid', () => {
         const result = validateClusterGrid({ x: 16, y: -1, z: 24 });
         expect(result.ok).toBe(false);
         if (!result.ok) {
-          expect(result.error.code).toBe('hdrp-grid-invalid');
+          expect(result.error.code).toBe('standard-profile-invalid');
           expect(result.error.hint).toContain('positive integer');
-          expect(result.error.detail).toEqual({ x: 16, y: -1, z: 24 });
+          expect(result.error.detail).toEqual({
+            field: 'clusterGrid',
+            actual: { x: 16, y: -1, z: 24 },
+          });
         }
       });
 
@@ -4977,10 +4982,13 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
         const result = validateClusterGrid({ x: 16, y: 9, z: 65 });
         expect(result.ok).toBe(false);
         if (!result.ok) {
-          expect(result.error.code).toBe('hdrp-grid-invalid');
+          expect(result.error.code).toBe('standard-profile-invalid');
           expect(result.error.hint).toContain('[1, 64]');
           expect(result.error.expected).toContain('[1, 64]');
-          expect(result.error.detail).toEqual({ x: 16, y: 9, z: 65 });
+          expect(result.error.detail).toEqual({
+            field: 'clusterGrid',
+            actual: { x: 16, y: 9, z: 65 },
+          });
         }
       });
 
@@ -5002,21 +5010,24 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
       });
     });
 
-    describe('HdrpInstallError shape', () => {
+    describe('StandardProfileInvalidError shape', () => {
       // AC-23: charter P3 triple-set .code / .hint / .expected + .detail.{x,y,z}
       it('carries charter P3 triple-set with detail', () => {
-        const err = new HdrpInstallError(0, 9, 24);
-        expect(err.code).toBe('hdrp-grid-invalid');
+        const err = new StandardProfileInvalidError('clusterGrid invalid', {
+          field: 'clusterGrid',
+          actual: { x: 0, y: 9, z: 24 },
+        });
+        expect(err.code).toBe('standard-profile-invalid');
         expect(err.hint).toContain('positive integer');
         expect(err.expected).toContain('[1, 64]');
-        expect(err.detail).toEqual({ x: 0, y: 9, z: 24 });
+        expect(err.detail).toEqual({ field: 'clusterGrid', actual: { x: 0, y: 9, z: 24 } });
       });
     });
   });
 }
 
 {
-  // --- from hdrp-index-list-overflow-once.test.ts ---
+  // --- from standard-cluster-index-overflow-once.test.ts ---
   function makeIdentityMat4(): Mat4 {
     return mat4.identity(mat4.create());
   }
@@ -5077,7 +5088,7 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
     });
   });
 
-  // ── hdrp-index-list-overflow RuntimeError class shape ────────────────────────
+  // ── Standard cluster index-overflow RuntimeError class shape ─────────────────
 
   // ── AC-03 guardrail: URP LIGHT_ARRAY_MAX_SLOTS=4 + 5 PointLights ─────────────
   //
@@ -5091,180 +5102,14 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
       expect(LIGHT_ARRAY_MAX_SLOTS).toBe(4);
     });
 
-    it('POINT_LIGHT_STD430_BYTES and SPOT_LIGHT_STD430_BYTES still match URP specs', async () => {
+    it('POINT_LIGHT_STD430_BYTES and SPOT_LIGHT_STD430_BYTES match the current URP payloads', async () => {
       const { POINT_LIGHT_STD430_BYTES, SPOT_LIGHT_STD430_BYTES } = await import(
         '../../../render/src/light-buffer-layout'
       );
       expect(POINT_LIGHT_STD430_BYTES).toBe(32);
-      // feat-20260625-spot-light-shadow-mapping M2 / w8 (D-4): SpotLight grew
-      // 48 -> 64 for the shadowAtlasTile i32 clip-signal lane (4th vec4 column).
-      expect(SPOT_LIGHT_STD430_BYTES).toBe(64);
-    });
-  });
-}
-
-{
-  // --- from hdrp-light-budget.test.ts ---
-
-  // ── Budget gate unit logic (the pure gate w23 will embed) ─────────────────────
-
-  const HDRP_BUDGET = 256;
-
-  function enforceLightBudget(
-    totalLightCount: number,
-    oncePerFrameFired: Set<string>,
-    fire: (code: string, errors: unknown[]) => void,
-  ): number {
-    if (totalLightCount <= HDRP_BUDGET) {
-      return totalLightCount;
-    }
-    // Truncate to budget.
-    const truncated = HDRP_BUDGET;
-    if (!oncePerFrameFired.has('hdrp-light-budget-exceeded')) {
-      oncePerFrameFired.add('hdrp-light-budget-exceeded');
-      fire('hdrp-light-budget-exceeded', [totalLightCount, HDRP_BUDGET]);
-    }
-    return truncated;
-  }
-
-  describe('HDRP light budget enforcement gate (AC-06/AC-07)', () => {
-    it('256 lights: no fire, returns 256 (AC-06 boundary)', () => {
-      const fired = new Set<string>();
-      const errors: Array<{ code: string; actual: number; budget: number }> = [];
-      const fireFn = (_code: string, args: unknown[]) => {
-        errors.push({
-          code: 'hdrp-light-budget-exceeded',
-          actual: args[0] as number,
-          budget: args[1] as number,
-        });
-      };
-
-      const result = enforceLightBudget(256, fired, fireFn);
-      expect(result).toBe(256);
-      expect(fired.size).toBe(0);
-      expect(errors.length).toBe(0);
-    });
-
-    it('257 lights: fires once, returns 256 (AC-07 truncation)', () => {
-      const fired = new Set<string>();
-      const errors: Array<{ code: string; actual: number; budget: number }> = [];
-      const fireFn = (_code: string, args: unknown[]) => {
-        errors.push({
-          code: 'hdrp-light-budget-exceeded',
-          actual: args[0] as number,
-          budget: args[1] as number,
-        });
-      };
-
-      const result = enforceLightBudget(257, fired, fireFn);
-      expect(result).toBe(256);
-      expect(fired.size).toBe(1);
-      expect(fired.has('hdrp-light-budget-exceeded')).toBe(true);
-      expect(errors.length).toBe(1);
-      expect(errors[0]?.actual).toBe(257);
-      expect(errors[0]?.budget).toBe(256);
-    });
-
-    it('same-frame subsequent overflow suppressed (warn-once-per-frame-bucket)', () => {
-      // Simulate frame already having fired the budget error.
-      const fired = new Set<string>(['hdrp-light-budget-exceeded']);
-      const errors: Array<{ code: string; actual: number; budget: number }> = [];
-      const fireFn = (_code: string, args: unknown[]) => {
-        errors.push({
-          code: 'hdrp-light-budget-exceeded',
-          actual: args[0] as number,
-          budget: args[1] as number,
-        });
-      };
-
-      // Even with 300 lights on the same frame, it should not fire again.
-      const result = enforceLightBudget(300, fired, fireFn);
-      expect(result).toBe(256);
-      expect(errors.length).toBe(0);
-    });
-
-    it('second frame fires again (fresh bucket)', () => {
-      // New frame: empty Set.
-      const fired = new Set<string>();
-      const errors: Array<{ code: string; actual: number; budget: number }> = [];
-      const fireFn = (_code: string, args: unknown[]) => {
-        errors.push({
-          code: 'hdrp-light-budget-exceeded',
-          actual: args[0] as number,
-          budget: args[1] as number,
-        });
-      };
-
-      const result = enforceLightBudget(258, fired, fireFn);
-      expect(result).toBe(256);
-      expect(errors.length).toBe(1);
-      expect(errors[0]?.actual).toBe(258);
-      expect(errors[0]?.budget).toBe(256);
-    });
-
-    it('second frame with exactly 256 does not fire (fresh bucket, under budget)', () => {
-      const fired = new Set<string>();
-      const errors: Array<{ code: string; actual: number; budget: number }> = [];
-      const fireFn = (_code: string, args: unknown[]) => {
-        errors.push({
-          code: 'hdrp-light-budget-exceeded',
-          actual: args[0] as number,
-          budget: args[1] as number,
-        });
-      };
-
-      const result = enforceLightBudget(256, fired, fireFn);
-      expect(result).toBe(256);
-      expect(errors.length).toBe(0);
-    });
-
-    it('0 lights returns 0 (empty scene, no fire)', () => {
-      const fired = new Set<string>();
-      const errors: Array<{ code: string; actual: number; budget: number }> = [];
-      const fireFn = (_code: string, args: unknown[]) => {
-        errors.push({
-          code: 'hdrp-light-budget-exceeded',
-          actual: args[0] as number,
-          budget: args[1] as number,
-        });
-      };
-
-      const result = enforceLightBudget(0, fired, fireFn);
-      expect(result).toBe(0);
-      expect(errors.length).toBe(0);
-    });
-
-    it('HDRP_BUDGET constant must be 256 (D-scope anchor)', () => {
-      expect(HDRP_BUDGET).toBe(256);
-    });
-  });
-
-  // ── Integration pattern: once-per-frame Set complements existing hdrpOncePerFrameFired ──
-
-  describe('hdrpOncePerFrameFired Set dedup semantics', () => {
-    it('empty set allows first fire', () => {
-      const fired = new Set<string>();
-      expect(fired.has('hdrp-light-budget-exceeded')).toBe(false);
-    });
-
-    it('set with entry suppresses subsequent fires on the same code', () => {
-      const fired = new Set<string>(['hdrp-light-budget-exceeded']);
-      expect(fired.has('hdrp-light-budget-exceeded')).toBe(true);
-    });
-
-    it('hdrp-light-budget-exceeded is independent from hdrp-index-list-overflow', () => {
-      const fired = new Set<string>(['hdrp-index-list-overflow']);
-      // Budget-exceeded should still fire even if index-list-overflow already fired this frame.
-      expect(fired.has('hdrp-light-budget-exceeded')).toBe(false);
-      expect(fired.has('hdrp-index-list-overflow')).toBe(true);
-    });
-
-    it('clearing the set (new frame) allows re-fire', () => {
-      const fired = new Set<string>(['hdrp-light-budget-exceeded']);
-      fired.clear();
-      expect(fired.has('hdrp-light-budget-exceeded')).toBe(false);
-      // The recordFrame entry clears hdrpOncePerFrameFired when frameNumber increments.
-      // This test verifies the clear() semantics match the expected new-frame behaviour.
+      // SpotLight's projector receiver controls and shadow intensity occupy
+      // the appended fifth vec4 column; point-light layout remains unchanged.
+      expect(SPOT_LIGHT_STD430_BYTES).toBe(80);
     });
   });
 }
@@ -5275,13 +5120,13 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
     it('creates a RenderPipelineAsset with HDRP pipelineId and clusterGrid config', () => {
       const asset: RenderPipelineAsset = {
         kind: 'render-pipeline',
-        pipelineId: 'forgeax::hdrp',
+        pipelineId: 'forgeax::standard',
         config: {
           clusterGrid: { x: 16, y: 9, z: 24 },
         },
       };
 
-      expect(asset.pipelineId).toBe('forgeax::hdrp');
+      expect(asset.pipelineId).toBe('forgeax::standard');
       expect(asset.kind).toBe('render-pipeline');
       expect(asset.config?.clusterGrid).toBeDefined();
       expect(asset.config?.clusterGrid?.x).toBe(16);
@@ -5292,17 +5137,17 @@ vi.mock('@forgeax/engine-rhi-wgpu', () => {
     it('creates a RenderPipelineAsset with URP pipelineId and no clusterGrid', () => {
       const asset: RenderPipelineAsset = {
         kind: 'render-pipeline',
-        pipelineId: 'forgeax::urp',
+        pipelineId: 'forgeax::standard',
       };
 
-      expect(asset.pipelineId).toBe('forgeax::urp');
+      expect(asset.pipelineId).toBe('forgeax::standard');
       expect(asset.config?.clusterGrid).toBeUndefined();
     });
 
     it('passCount field is still supported alongside clusterGrid', () => {
       const asset: RenderPipelineAsset = {
         kind: 'render-pipeline',
-        pipelineId: 'forgeax::hdrp',
+        pipelineId: 'forgeax::standard',
         config: {
           passCount: 3,
           clusterGrid: { x: 16, y: 9, z: 24 },