@forgeax/engine-runtime 0.1.21 → 0.1.24

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

@@ -0,0 +1,370 @@
+// @ts-nocheck — merged file: cross-source node:fs/node:path imports outside @types/node coverage in runtime tsconfig
+// Consolidated by feat-20260609-test-pool-startup-reduction-merge-tiny-test-files
+// biome-ignore-all lint/complexity/noUselessLoneBlockStatements: block-scope isolation between merged source files (consolidation paradigm)
+//
+// Source files (N=33):
+//   - packages/runtime/__tests__/create-renderer-fallback.test.ts
+//   - packages/runtime/src/__tests__/cluster-binner.test.ts
+//   - packages/runtime/src/__tests__/create-renderer-fallback-shader-manifest.test.ts
+//   - packages/runtime/src/__tests__/create-renderer-uniform-fallback.test.ts
+//   - packages/runtime/src/__tests__/createRenderer.test.ts
+//   - packages/runtime/src/__tests__/dispatch-sort.test.ts
+//   - packages/runtime/src/__tests__/engine-metrics.test.ts
+//   - packages/runtime/src/__tests__/device/gpu-residency-caps-guard.test.ts
+//   - packages/runtime/src/__tests__/pass-selector.test.ts
+//   - packages/runtime/src/__tests__/pipeline-builder.test.ts
+//   - packages/runtime/src/__tests__/pipeline-cache-key-topology.test.ts
+//   - packages/runtime/src/__tests__/pipeline-rename-grep-gate.test.ts
+//   - packages/runtime/src/__tests__/pipeline-vertex-stride-branch.test.ts
+//   - packages/runtime/src/__tests__/post-process-register.test.ts
+//   - packages/runtime/src/__tests__/record-all-topology.test.ts
+//   - packages/runtime/src/__tests__/record-draw-branch.test.ts
+//   - packages/runtime/src/__tests__/record-strip-index-format.test.ts
+//   - packages/runtime/src/__tests__/render-query-regression.test.ts
+//   - packages/runtime/src/__tests__/renderer-draw-world.test.ts
+//   - packages/runtime/src/__tests__/renderer-input-snapshot.test.ts
+//   - packages/runtime/src/__tests__/renderer-read-pixels.test.ts
+//   - packages/runtime/src/__tests__/renderer-ready.test.ts
+//   - packages/runtime/src/__tests__/renderstate-pipeline-cache.test.ts
+//   - packages/runtime/src/__tests__/storage-buffer-caps.test.ts
+//   - packages/runtime/src/__tests__/device/gpu-residency.test.ts
+//   - 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__/hdrp-pipeline-asset-config.test.ts
+//   - packages/runtime/src/__tests__/m7-hdrp-demo-shape.test.ts
+//
+// Paradigm: each block-scope wraps a source file. ancestorTitles[0] is the
+// source-preserved inner describe (NOT the source filename for these 3 files
+// — recovery path: vitest report ancestorTitles -> grep this file -> upstream
+// `// ─── from <name>.test.ts ───` block separator -> source filename).
+// Top-level imports merged + deduped.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HANDLE_CUBE, HANDLE_TRIANGLE, resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import type { World as WorldType } from '@forgeax/engine-ecs';
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import {
+  buildMeshAttributeMapForUvSets,
+  createBoxGeometry,
+  createConeGeometry,
+  createCylinderGeometry,
+  createPlaneGeometry,
+  createSphereGeometry,
+  createTorusGeometry,
+  PROCEDURAL_FLOATS_PER_VERTEX,
+} from '@forgeax/engine-geometry';
+import { type Mat4, mat4, type Vec3, vec3 } from '@forgeax/engine-math';
+import type { Renderer as RendererType } from '@forgeax/engine-render';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import {
+  err,
+  ok,
+  type PipelineLayout,
+  type RenderPipeline,
+  type Result,
+  type RhiCaps,
+  type RhiDevice,
+  RhiError,
+  ok as rhiOk,
+  type ShaderModule,
+} from '@forgeax/engine-rhi';
+import {
+  acquireCanvasContext as acquireNullCanvasContext,
+  createShaderModule as createNullShaderModule,
+  RhiNullAdapter,
+} from '@forgeax/engine-rhi-null';
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import {
+  findVariantByKey,
+  type MaterialShaderEntry,
+  type MaterialShaderManifestEntry,
+  type MaterialShaderManifestVariant,
+} from '@forgeax/engine-shader';
+import {
+  type AssetError,
+  type EquirectAsset,
+  type Handle,
+  type MaterialRenderState,
+  type MeshAsset,
+  type PassSelector,
+  type PrimitiveTopology,
+  type RenderPipelineAsset,
+  type TextureAsset,
+  toShared,
+} from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  bin,
+  type ClusterBinError,
+  calculateSphereClusterBounds,
+  clusterSpaceObjectAabb,
+  deriveCullingRadius,
+  ndcPositionToCluster,
+  viewZToZSlice,
+} from '../../../render/src/cluster-binner';
+import { GpuResidencyCache } from '../../../render/src/device/gpu-residency';
+import { createEngineMetrics } from '../../../render/src/engine-metrics';
+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 {
+  buildPipelineForMaterialShader,
+  type PipelineBuilderContext,
+  type PipelineBuilderShaderModuleFactory,
+} from '../../../render/src/pipeline-builder';
+import {
+  cacheKeyOf,
+  createHdrpBindGroupLayoutDescriptor,
+  type PipelineSpec,
+} from '../../../render/src/pipeline-spec';
+import {
+  deriveRenderDataCubemap,
+  deriveRenderDataMesh,
+  deriveRenderDataTexture,
+} from '../../../render/src/render-data';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+import { matchPass } from '../../../render/src/systems/pass-selector';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
+
+function makeExplicitNullRhi(spies: {
+  setIndexBuffer: ReturnType<typeof vi.fn>;
+  setVertexBuffer: ReturnType<typeof vi.fn>;
+  draw: ReturnType<typeof vi.fn>;
+  drawIndexed: ReturnType<typeof vi.fn>;
+}): unknown {
+  const adapter = new RhiNullAdapter();
+  const requestDevice = adapter.requestDevice.bind(adapter);
+  adapter.requestDevice = async () => {
+    const result = await requestDevice();
+    if (result.ok) {
+      const device = result.value;
+      const createCommandEncoder = device.createCommandEncoder.bind(device);
+      device.createCommandEncoder = (desc) => {
+        const encoderResult = createCommandEncoder(desc);
+        if (!encoderResult.ok) return encoderResult;
+        const encoder = encoderResult.value;
+        const beginRenderPass = encoder.beginRenderPass.bind(encoder);
+        encoder.beginRenderPass = (passDesc) => {
+          const pass = beginRenderPass(passDesc);
+          const draw = pass.draw.bind(pass);
+          const drawIndexed = pass.drawIndexed.bind(pass);
+          const setIndexBuffer = pass.setIndexBuffer.bind(pass);
+          const setVertexBuffer = pass.setVertexBuffer.bind(pass);
+          pass.draw = (...args) => {
+            spies.draw(...args);
+            draw(...args);
+          };
+          pass.drawIndexed = (...args) => {
+            spies.drawIndexed(...args);
+            drawIndexed(...args);
+          };
+          pass.setIndexBuffer = (...args) => {
+            spies.setIndexBuffer(...args);
+            setIndexBuffer(...args);
+          };
+          pass.setVertexBuffer = (...args) => {
+            spies.setVertexBuffer(...args);
+            setVertexBuffer(...args);
+          };
+          return pass;
+        };
+        return { ok: true, value: encoder };
+      };
+    }
+    return result;
+  };
+  return {
+    requestAdapter: async () => ({ ok: true, value: adapter }),
+    acquireCanvasContext: acquireNullCanvasContext,
+    createShaderModule: (device: unknown, desc: { code: string; label?: string }) =>
+      createNullShaderModule(device as never, desc),
+  };
+}
+
+vi.mock('@forgeax/engine-rhi-wgpu', () => {
+  return {
+    rhi: {
+      requestAdapter: async () => ({
+        ok: false,
+        error: {
+          code: 'adapter-unavailable',
+          expected: 'adapter available',
+          hint: 'default mock fail',
+        },
+      }),
+      getPreferredCanvasFormat: () => 'bgra8unorm',
+      acquireCanvasContext: () => ({
+        ok: false,
+        error: {
+          code: 'webgpu-runtime-error',
+          expected: 'context available',
+          hint: 'default mock fail',
+        },
+      }),
+    },
+    ensureReady: async () => undefined,
+  };
+});
+
+void [
+  Camera,
+  ChildOf,
+  GpuResidencyCache,
+  HANDLE_CUBE,
+  HANDLE_TRIANGLE,
+  HdrpInstallError,
+  MeshFilter,
+  MeshRenderer,
+  PROCEDURAL_FLOATS_PER_VERTEX,
+  RhiError,
+  RhiNullAdapter,
+  Transform,
+  World,
+  acquireNullCanvasContext,
+  afterEach,
+  assertStorageBufferCap,
+  beforeEach,
+  bin,
+  buildMeshAttributeMapForUvSets,
+  buildPbrPipelineLayouts,
+  buildPbrViewBglEntries,
+  buildPipelineForMaterialShader,
+  cacheKeyOf,
+  calculateSphereClusterBounds,
+  clusterSpaceObjectAabb,
+  createBoxGeometry,
+  createConeGeometry,
+  createCylinderGeometry,
+  createEngineMetrics,
+  createHdrpBindGroupLayoutDescriptor,
+  createNullShaderModule,
+  createPlaneGeometry,
+  createSphereGeometry,
+  createTorusGeometry,
+  defineComponent,
+  deriveCullingRadius,
+  deriveRenderDataCubemap,
+  deriveRenderDataMesh,
+  deriveRenderDataTexture,
+  describe,
+  dirname,
+  err,
+  existsSync,
+  expect,
+  extractFrame,
+  fileURLToPath,
+  findVariantByKey,
+  it,
+  makeExplicitNullRhi,
+  makeMockShaderRegistry,
+  mat4,
+  matchPass,
+  ndcPositionToCluster,
+  ok,
+  prepareExtractContext,
+  readFileSync,
+  resolve,
+  resolveAssetHandle,
+  rhiOk,
+  standardMaterialShaderVariants,
+  toShared,
+  validateClusterGrid,
+  vec3,
+  vi,
+  viewZToZSlice,
+];
+type __MergedKeep =
+  | AssetError
+  | ClusterBinError
+  | EquirectAsset
+  | Handle
+  | Mat4
+  | MaterialRenderState
+  | MaterialShaderEntry
+  | MaterialShaderManifestEntry
+  | MaterialShaderManifestVariant
+  | MeshAsset
+  | PassSelector
+  | PbrCaps
+  | PipelineBuilderContext
+  | PipelineBuilderShaderModuleFactory
+  | PipelineLayout
+  | PipelineSpec
+  | PrimitiveTopology
+  | RenderPipeline
+  | RenderPipelineAsset
+  | RendererType
+  | Result
+  | RhiCaps
+  | RhiDevice
+  | ShaderModule
+  | TextureAsset
+  | Vec3
+  | WorldType;
+
+{
+  // ── Light budget error class shape ─────────────────────────────────────────────
+
+  // ── Index list overflow error class shape ─────────────────────────────────────
+
+  // ── Caps gate 5 scenarios (AC-17) ─────────────────────────────────────────────
+  // Note: the caps router lives in hdrp-pipeline.ts. These tests verify
+  // the installPipeline behaviour by mocking device.caps.
+
+  describe('HDRP caps gate 5 scenarios (AC-17)', () => {
+    it('caps=0 (uniform fallback) yields ok(false)', async () => {
+      const { assertStorageBufferCap } = await import('../../../render/src/light-buffer-layout');
+      const result = assertStorageBufferCap(0);
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.value).toBe(false);
+      }
+    });
+
+    it('caps=1 (insufficient, partial storage) yields err', async () => {
+      const { assertStorageBufferCap } = await import('../../../render/src/light-buffer-layout');
+      const result = assertStorageBufferCap(1);
+      expect(result.ok).toBe(false);
+    });
+
+    it('caps=3 (insufficient, below 4) yields err', async () => {
+      const { assertStorageBufferCap } = await import('../../../render/src/light-buffer-layout');
+      const result = assertStorageBufferCap(3);
+      expect(result.ok).toBe(false);
+    });
+
+    it('caps=4 (sufficient) yields ok(true)', async () => {
+      const { assertStorageBufferCap } = await import('../../../render/src/light-buffer-layout');
+      const result = assertStorageBufferCap(4);
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.value).toBe(true);
+      }
+    });
+
+    it('caps=8 (sufficient, above minimum) yields ok(true)', async () => {
+      const { assertStorageBufferCap } = await import('../../../render/src/light-buffer-layout');
+      const result = assertStorageBufferCap(8);
+      expect(result.ok).toBe(true);
+      if (result.ok) {
+        expect(result.value).toBe(true);
+      }
+    });
+  });
+
+  // ── RuntimeErrorCode union member count (12 -> 15) ───────────────────────────
+}

package/src/__tests__/point-light-shadow.browser.test.ts

@@ -400,4 +400,5 @@ it.skipIf(!browserReady)(
       canvas.remove();
     }
   },
+  60_000,
 );

package/src/__tests__/point-light-shadow.unit.test.ts

@@ -19,10 +19,9 @@ import { describe, expect, it } from 'vitest';
 import { validatePointLightShadowData } from '../../../render/src/components/light-helpers';
 import { ShadowInvalidConfigError } from '../../../render/src/errors/render';
 import {
-  BYTES_PER_LIGHT_SLOT,
-  LIGHTSLOT_LAYOUT,
-  packLightSlot,
-  SPOT_LIGHT_PROJECTOR_FLAG,
+  BYTES_PER_DIRECT_LIGHT_SLOT,
+  DIRECT_LIGHT_SLOT_LAYOUT,
+  packDirectLightSlot,
 } from '../../../render/src/light-buffer-layout';
 import { buildPointShadowMatrices } from '../../../render/src/render-system-extract';
 import {
@@ -551,7 +550,7 @@ function spawnValidatedPointShadow(
     });
 
     describe('standard point shadow light-slot packing (AC-05)', () => {
-      it('AC-13: packLightSlot writes shadow info onto LightSlot pad lanes (byte 52..64)', () => {
+      it('AC-13: packDirectLightSlot writes point shadow identity metadata', () => {
         const snap = {
           kind: 'point' as const,
           position: vec3.create(1, 2, 3),
@@ -559,26 +558,18 @@ function spawnValidatedPointShadow(
           intensity: 1,
           invRangeSquared: 0.04,
         };
-        // Without shadow info: layer = -1 sentinel; near/far = 0.
-        const noShadow = packLightSlot(snap);
+        // Without shadow info: layer = -1 sentinel in metadata word 17.
+        const noShadow = packDirectLightSlot(snap);
         const i32NoShadow = new Int32Array(noShadow.buffer);
-        expect(i32NoShadow[13]).toBe(-1); // sentinel
-        expect(noShadow[14]).toBe(0); // near
-        expect(noShadow[15]).toBe(0); // far
-
-        // With shadow info: layer 2, near 0.1, far 25 — matches PointLightShadow defaults.
-        const withShadow = packLightSlot(snap, {
-          shadowAtlasLayer: 2,
-          near: 0.1,
-          far: 25,
-        });
+        expect(i32NoShadow[17]).toBe(-1); // sentinel
+
+        // Extract joins the PointLightShadow layer before packing.
+        const withShadow = packDirectLightSlot({ ...snap, shadowAtlasLayer: 2 });
         const i32Shadow = new Int32Array(withShadow.buffer);
-        expect(i32Shadow[13]).toBe(2);
-        expect(withShadow[14]).toBeCloseTo(0.1, 5);
-        expect(withShadow[15]).toBe(25);
+        expect(i32Shadow[17]).toBe(2);
       });
 
-      it('AC-13: spot light packLightSlot writes its shadow defaults into the tail lanes', () => {
+      it('AC-13: unified Spot packing writes shadow metadata', () => {
         const spotSnap = {
           kind: 'spot' as const,
           entity: 0,
@@ -596,86 +587,15 @@ function spawnValidatedPointShadow(
           farPlane: 50,
           shadowAtlasTile: -1,
         };
-        // SpotLight uses the former pad lanes for the shadow intensity and
-        // PCF-kernel defaults. The atlas tile remains the -1 sentinel while
-        // projector/shadow consumers read the appended payload fields.
-        const packed = packLightSlot(spotSnap, {
-          shadowAtlasLayer: 0,
-          near: 0.1,
-          far: 25,
-        });
+        const packed = packDirectLightSlot(spotSnap);
         const i32 = new Int32Array(packed.buffer);
-        expect(i32[13]).toBe(-1); // sentinel; spot lights stay shadowless
-        expect(packed[14]).toBeCloseTo(1, 5);
-        expect(packed[15]).toBeCloseTo(3, 5);
+        expect(i32[17]).toBe(-1);
       });
 
-      it('keeps authored spot shadow intensity and PCF width in the cluster lanes', () => {
-        const spotSnap = {
-          kind: 'spot' as const,
-          entity: 0,
-          position: vec3.create(0, 0, 0),
-          direction: vec3.create(0, -1, 0),
-          color: vec3.create(1, 1, 1),
-          intensity: 1,
-          invRangeSquared: 0,
-          cosInner: 0.95,
-          cosOuter: 0.85,
-          castShadow: true,
-          lightViewProj: undefined,
-          mapSize: 2048,
-          nearPlane: 0.1,
-          farPlane: 50,
-          shadowAtlasTile: 2,
-          shadowIntensity: 0.35,
-          pcfKernelSize: 5,
-        };
-        const packed = packLightSlot(spotSnap);
-        const i32 = new Int32Array(packed.buffer);
-        expect(i32[13]).toBe(2);
-        expect(packed[14]).toBeCloseTo(0.35, 5);
-        expect(packed[15]).toBeCloseTo(5, 5);
-      });
-
-      it('marks the accepted projector without losing a shadow tile', () => {
-        const spotSnap = {
-          kind: 'spot' as const,
-          entity: 7,
-          position: vec3.create(0, 2, 0),
-          direction: vec3.create(0, -1, 0),
-          color: vec3.create(1, 1, 1),
-          intensity: 1,
-          invRangeSquared: 0.04,
-          cosInner: 0.95,
-          cosOuter: 0.85,
-          castShadow: true,
-          lightViewProj: new Float32Array(16),
-          mapSize: 512,
-          nearPlane: 0.1,
-          farPlane: 25,
-          shadowAtlasTile: 2,
-          projectorAsset: { kind: 'texture' } as never,
-        };
-        const packed = packLightSlot(spotSnap, undefined, true);
-        const encoded = new Int32Array(packed.buffer)[13] ?? 0;
-        expect(encoded & SPOT_LIGHT_PROJECTOR_FLAG).toBe(SPOT_LIGHT_PROJECTOR_FLAG);
-        expect(encoded & (SPOT_LIGHT_PROJECTOR_FLAG - 1)).toBe(2);
-
-        const projectorOnly = packLightSlot({ ...spotSnap, shadowAtlasTile: -1 }, undefined, true);
-        const projectorOnlyEncoded = new Int32Array(projectorOnly.buffer)[13] ?? 0;
-        expect(projectorOnlyEncoded).toBe(SPOT_LIGHT_PROJECTOR_FLAG);
-      });
-
-      it('AC-05: LIGHTSLOT_LAYOUT byteSize unchanged at 64 (no-regression for standard)', () => {
-        // The pad-lane re-purposing must not change the total LightSlot size:
-        // the std430 vec4 stride is preserved; only the field semantics within
-        // bytes 52..64 changed (u32 pad -> i32 layer + f32 near + f32 far).
-        expect(BYTES_PER_LIGHT_SLOT).toBe(64);
-        expect(LIGHTSLOT_LAYOUT.byteSize).toBe(64);
-        expect(LIGHTSLOT_LAYOUT.shadowAtlasLayerOffset).toBe(52);
-        expect(LIGHTSLOT_LAYOUT.shadowPayloadOffset).toBe(52);
-        expect(LIGHTSLOT_LAYOUT.shadowNearOffset).toBe(56);
-        expect(LIGHTSLOT_LAYOUT.shadowFarOffset).toBe(60);
+      it('AC-05: DIRECT_LIGHT_SLOT_LAYOUT keeps the five-row ABI', () => {
+        expect(BYTES_PER_DIRECT_LIGHT_SLOT).toBe(80);
+        expect(DIRECT_LIGHT_SLOT_LAYOUT.byteSize).toBe(80);
+        expect(DIRECT_LIGHT_SLOT_LAYOUT.shadowByteOffset).toBe(68);
       });
     });