@forgeax/engine-runtime 0.1.21 → 0.1.24

package/src/__tests__/record-strip-index-format.cases.unit.test.ts

@@ -0,0 +1,419 @@
+// @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;
+
+{
+  // --- from record-strip-index-format.test.ts ---
+  const ID = 'my-game::strip-material';
+
+  // Local mkSpec helper (M2-T4 fixup: strip-index block is outside M9-T01
+  // scope; mkSpec from M9-T01 block is not visible here).
+  function mkSpec(
+    id: string,
+    isHdr: boolean,
+    renderState?: MaterialRenderState,
+    topology?: PrimitiveTopology,
+    indexFormat?: 'uint16' | 'uint32',
+    variantSet?: string,
+    passKind = 'forward',
+    sampleCount: 1 | 4 = 1,
+  ): PipelineSpec {
+    const colorFormat: GPUTextureFormat = isHdr
+      ? ('rgba16float' as unknown as GPUTextureFormat)
+      : ('bgra8unorm-srgb' as unknown as GPUTextureFormat);
+    return {
+      shader: { id, passKind, variantSet },
+      attachments: {
+        colorFormats: passKind === 'shadow-caster' ? [] : [colorFormat],
+        depthFormat:
+          passKind === 'shadow-caster'
+            ? ('depth32float' as unknown as GPUTextureFormat)
+            : ('depth24plus-stencil8' as unknown as GPUTextureFormat),
+        sampleCount,
+      },
+      geometry: {
+        topology: topology ?? 'triangle-list',
+        stripIndexFormat: indexFormat,
+        vertexLayout: {
+          position: new Float32Array(0),
+          normal: new Float32Array(0),
+          uv: new Float32Array(0),
+          tangent: new Float32Array(0),
+        },
+      },
+      renderState,
+    };
+  }
+
+  describe('cacheKeyOf strip-index dimension (M5 w15 - AC-08)', () => {
+    it('(a) triangle-strip uint16 vs uint32 -> distinct keys', () => {
+      const u16 = cacheKeyOf(mkSpec(ID, false, undefined, 'triangle-strip', 'uint16'));
+      const u32 = cacheKeyOf(mkSpec(ID, false, undefined, 'triangle-strip', 'uint32'));
+      expect(u16).not.toBe(u32);
+    });
+
+    it('(b) line-strip uint16 vs uint32 -> distinct keys', () => {
+      const u16 = cacheKeyOf(mkSpec(ID, false, undefined, 'line-strip', 'uint16'));
+      const u32 = cacheKeyOf(mkSpec(ID, false, undefined, 'line-strip', 'uint32'));
+      expect(u16).not.toBe(u32);
+    });
+
+    it('(c) AC-03: triangle-list ignores indexFormat (byte-identical key)', () => {
+      const u16 = cacheKeyOf(mkSpec(ID, false, undefined, 'triangle-list', 'uint16'));
+      const u32 = cacheKeyOf(mkSpec(ID, false, undefined, 'triangle-list', 'uint32'));
+      const omitted = cacheKeyOf(mkSpec(ID, false, undefined, 'triangle-list'));
+      expect(u16).toBe(u32);
+      expect(u16).toBe(omitted);
+    });
+
+    it('(c) AC-03: line-list and point-list ignore indexFormat too', () => {
+      for (const topo of ['line-list', 'point-list'] as const) {
+        const u16 = cacheKeyOf(mkSpec(ID, false, undefined, topo, 'uint16'));
+        const u32 = cacheKeyOf(mkSpec(ID, false, undefined, topo, 'uint32'));
+        expect(u16).toBe(u32);
+      }
+    });
+
+    it('(c) AC-03: indexFormat does not perturb the non-strip key shape', () => {
+      // M2-T4: key format includes full axes (passKind:variantSet:colorFormats:...)
+      // not the legacy :ldr prefix. The key carries the 4-axis structure with
+      // vl:<hash> at the tail; indexFormat never appends for non-strip topology.
+      // bug-20260708 M2 (b): variantSet=undefined now serializes as sentinel
+      // `~` (was empty `::`).
+      const withIdx = cacheKeyOf(mkSpec(ID, false, undefined, 'triangle-list', 'uint32'));
+      expect(
+        withIdx.startsWith(`${ID}:forward:~:bgra8unorm-srgb:depth24plus-stencil8:1:triangle-list`),
+      ).toBe(true);
+      expect(withIdx.includes(':uint32')).toBe(false);
+    });
+
+    it('(d) strip topology with omitted indexFormat resolves to the triangle-strip topo segment', () => {
+      // Builder falls back to 'uint32' when stripIndexFormat is omitted; the key
+      // for an omitted-indexFormat strip stays stable (no undefined leakage).
+      const omitted = cacheKeyOf(mkSpec(ID, false, undefined, 'triangle-strip'));
+      expect(omitted.includes(':triangle-strip')).toBe(true);
+      expect(omitted.includes('undefined')).toBe(false);
+    });
+
+    it('(a) strip index dimension holds with a renderState present', () => {
+      const rs: MaterialRenderState = { cullMode: 'none' };
+      const u16 = cacheKeyOf(mkSpec(ID, false, rs, 'triangle-strip', 'uint16'));
+      const u32 = cacheKeyOf(mkSpec(ID, false, rs, 'triangle-strip', 'uint32'));
+      expect(u16).not.toBe(u32);
+    });
+  });
+}

package/src/__tests__/record-worldid-isolation.test.ts

@@ -6,10 +6,11 @@
 //
 // Anchors:
 //   plan-tasks.json m2 (patch assignment)
-//   plan-strategy D-1a #1 (instanceBuffers positive half) and #3 (instancesBgPerEntity)
+//   plan-strategy D-1a #1 (instanceBuffers positive half); bind groups are now
+//   shared by opaque buffer handles after the probe/identity layout split.
 //   requirements AC-07
 //
-// The 13 sites under test (plus 2 read-side instancesBgPerEntity reads) are
+// The production instance-buffer sites and the shared bind-group resolver are
 // located by their stable cache operation below; source line numbers are not
 // part of the contract and must not make this gate stale after extraction.
 //
@@ -29,7 +30,7 @@ import { describe, expect, it } from 'vitest';
  * Verify that a cache site uses a worldEntityKey composite key.
  * Scans the source file around the given line (within a window) for both
  * `worldEntityKey` and the cache operation (`targetPattern` such as
- * `instanceBuffers.get`, `instancesBgPerEntity` as second arg, etc.).
+ * `instanceBuffers.get`, etc.).
  */
 function expectWorldEntityKeyAt(
   filePath: string,
@@ -95,19 +96,16 @@ describe('production-path geometry instanceBuffers worldEntityKey', () => {
   });
 });
 
-// ── Sprite identity BG instancesBgPerEntity (D-1a #3) ──────────────────────
-
 const SPRITE_FILE = fileURLToPath(
   new URL('../../../render/src/record/main-pass-sprite-draws.ts', import.meta.url),
 );
 
-describe('production-path sprite identity instancesBgPerEntity worldEntityKey', () => {
-  it('identityInstBg entityKey uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
-      SPRITE_FILE,
-      findLine(SPRITE_FILE, 'frameState.instancesBgPerEntity', 0),
-      'main-pass-sprite-draws instancesBgPerEntity write',
-    );
+describe('production-path shared instance bind-group resolver', () => {
+  it('sprite identity and sprite-instance paths use the shared resolver', () => {
+    const src = readFileSync(SPRITE_FILE, 'utf8');
+    expect(src).toContain('const identityInstBg = resolveGeometryInstancesBindGroup(');
+    expect(src).toContain('const spriteInstBg = resolveGeometryInstancesBindGroup(');
+    expect(src).toContain('const spriteInstancesBg = resolveGeometryInstancesBindGroup(');
   });
 });
 
@@ -131,18 +129,6 @@ describe('production-path sprite Instances instanceBuffers worldEntityKey', () =
   });
 });
 
-// ── Sprite pass instancesBgPerEntity (D-1a #3) ─────────────────────────────
-
-describe('production-path sprite pass instancesBgPerEntity worldEntityKey', () => {
-  it('spriteInstancesBg entityKey write uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
-      SPRITE_FILE,
-      findLine(SPRITE_FILE, 'frameState.instancesBgPerEntity', 1),
-      'main-pass-sprite-draws sprite pass instancesBgPerEntity write',
-    );
-  });
-});
-
 // ── SpriteInstances instanceBuffers (D-1a #1) ──────────────────────────────
 
 describe('production-path SpriteInstances instanceBuffers worldEntityKey', () => {
@@ -197,15 +183,13 @@ describe('production-path shadow instanceBuffers worldEntityKey', () => {
   });
 });
 
-// ── Shadow pass instancesBgPerEntity (D-1a #3) ─────────────────────────────
-
-describe('production-path shadow instancesBgPerEntity worldEntityKey', () => {
-  it('shadowInstancesBg entityKey write uses worldEntityKey', () => {
-    expectWorldEntityKeyAt(
-      SHADOW_FILE,
-      findLine(SHADOW_FILE, 'c.frameState.instancesBgPerEntity', 0),
-      'shadow-pass instancesBgPerEntity write',
+describe('production-path shadow shared instance bind-group resolver', () => {
+  it('shadow pass resolves the bind group from the world-aware buffer cache', () => {
+    const src = readFileSync(SHADOW_FILE, 'utf8');
+    expect(src).toContain(
+      'const shadowInstancesBg = resolveGeometryInstancesBindGroup(c, shadowInstanceBuffer);',
     );
+    expect(src).toContain('worldEntityKey(entry.source.worldId, shadowInst.cacheKey)');
   });
 });