@forgeax/engine-runtime 0.1.23 → 0.1.24

package/src/__tests__/render-system-record-warn-once.cases.unit.test.ts

@@ -0,0 +1,418 @@
+// @ts-nocheck — merged file: indexed-access checks cascade across noUncheckedIndexedAccess for blocks originally outside src/ rootDir
+// 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=44):
+//   - packages/runtime/__tests__/antialias-from-f32.test.ts
+//   - packages/runtime/src/__tests__/bloom-gating.test.ts
+//   - packages/runtime/src/__tests__/camera-antialias.test.ts
+//   - packages/runtime/src/__tests__/camera-bloom.test.ts
+//   - packages/runtime/src/__tests__/camera-clear-schema.test.ts
+//   - packages/runtime/src/__tests__/camera-ortho.test.ts
+//   - packages/runtime/src/__tests__/fxaa-intermediate-texture.test.ts
+//   - packages/runtime/src/__tests__/fxaa-pipeline.test.ts
+//   - packages/runtime/src/__tests__/ibl-pipeline-cache.test.ts
+//   - packages/runtime/src/__tests__/ibl-runtime-probe.test.ts
+//   - packages/runtime/src/__tests__/render-system-record-warn-once.test.ts
+//   - packages/runtime/src/__tests__/shadow-skip-non-triangle.test.ts
+//   - packages/runtime/src/__tests__/skin-errors-kebab-case.test.ts
+//   - packages/runtime/src/__tests__/skybox-error.test.ts
+//   - packages/runtime/src/__tests__/skybox-shader-compile.test.ts
+//   - packages/runtime/src/__tests__/skylight-bind-group.test.ts
+//   - packages/runtime/src/__tests__/skylight-component.test.ts
+//   - packages/runtime/src/__tests__/skylight-fallback-path.test.ts
+//   - packages/runtime/src/__tests__/skylight-pipeline-layout.test.ts
+//   - packages/runtime/src/__tests__/tonemap-hdr-target.test.ts
+//   - packages/runtime/src/__tests__/tonemap-pipeline-split.test.ts
+//   - packages/runtime/src/__tests__/zero-camera-clear-fallback.test.ts
+//   - packages/runtime/src/components/__tests__/skin.test.ts
+//   - packages/runtime/src/systems/__tests__/advance-animation-player.test.ts
+//   - packages/runtime/src/systems/__tests__/graph-skybox.test.ts
+//   - packages/runtime/src/systems/__tests__/propagate-transforms.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-cap-gate.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-instances-coexist.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-palette-extract.test.ts
+//   - packages/runtime/src/systems/__tests__/skin-pipeline-routing.test.ts
+//   - packages/runtime/src/systems/__tests__/skybox-extract.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-boundary.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-clamp.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-frame-duration-negative.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-frame-duration-zero.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-loop.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-override-probe.test.ts
+//   - packages/runtime/src/systems/__tests__/sprite-animation-tick-regions-mismatch.test.ts
+//   - packages/runtime/src/systems/__tests__/tonemap.test.ts
+//   - packages/runtime/src/systems/__tests__/transparent-sort-config-get.test.ts
+//   - packages/runtime/src/systems/__tests__/transparent-sort-config-set.test.ts
+//   - packages/runtime/src/systems/__tests__/transparent-sort.test.ts
+//   - packages/runtime/src/__tests__/render-system-multi-material.test.ts
+//   - packages/runtime/src/__tests__/render-system-record-submesh.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 { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AnimationPlayer } from '@forgeax/engine-animation';
+import type { AssetRuntimeErrorCode } from '@forgeax/engine-assets-runtime';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { EntityHandle, World as WorldType } from '@forgeax/engine-ecs';
+import { ENTITY_NULL_RAW, World } from '@forgeax/engine-ecs';
+import { SpriteAnimationInvalidError } from '@forgeax/engine-ecs/projection';
+import { mat4, vec3 } from '@forgeax/engine-math';
+import type { RenderErrorCode, Renderer as RendererType } from '@forgeax/engine-render';
+import {
+  ANTIALIAS_FXAA,
+  ANTIALIAS_NONE,
+  BLOOM_DISABLED,
+  BLOOM_ENABLED,
+  CAMERA_PROJECTION_ORTHOGRAPHIC,
+  CAMERA_PROJECTION_PERSPECTIVE,
+  Camera,
+  MeshFilter,
+  MeshRenderer,
+  SkyboxBackground,
+  Skylight,
+} from '@forgeax/engine-render';
+import type { BindGroupEntry, Buffer, Sampler, Texture, TextureView } from '@forgeax/engine-rhi';
+import { ok as rhiOk } from '@forgeax/engine-rhi';
+import { ChildOf, Name, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { TONEMAP_LUMINANCE_EPSILON } from '@forgeax/engine-shader';
+import type { SkinErrorCode } from '@forgeax/engine-skinning';
+import {
+  Skin,
+  SkinInstancesCoexistForbiddenError,
+  SkinJointCountExceededError,
+  SkinJointDespawnedError,
+  SkinJointPathUnresolvedError,
+} from '@forgeax/engine-skinning';
+import type {
+  Handle,
+  MaterialAsset,
+  MeshAsset,
+  SkeletonAsset,
+  TextureFormat,
+} from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { worldInternal } from '../../../ecs/src/world-internal';
+import {
+  SPRITE_PLAYBACK_MODE_CLAMP,
+  SPRITE_PLAYBACK_MODE_LOOP,
+  SpriteAnimation,
+  SpriteRegionOverride,
+} from '../../../render/src/components';
+import {
+  type CameraProjection,
+  cameraProjectionFromF32,
+} from '../../../render/src/components/camera';
+import {
+  assembleMaterialWithSkylightEntries,
+  createSkylightFallback,
+  mergeSkylightIntoMaterialBgl,
+} from '../../../render/src/ibl/skylight-bind-group';
+import { buildPbrPipelineLayouts, buildUnlitMaterialBgl } from '../../../render/src/pbr-pipeline';
+import { INSTANCE_STORAGE_STRIDE_FLOATS } from '../../../render/src/record/mesh-ssbo';
+import { selectSwapChainFormat } from '../../../render/src/render-system';
+import { createSkinPaletteAllocator } from '../../../render/src/systems/skin-palette-allocator';
+import type { TransparentEntry } from '../../../render/src/systems/transparent-sort-config';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
+import { drawWithOwners } from './renderer-test-utils';
+
+function componentFieldType(component: { fields: Record<string, { type: string }> }, name: string) {
+  return component.fields[name]?.type;
+}
+
+function componentFieldDefault(
+  component: { fields: Record<string, { default?: unknown }> },
+  name: string,
+) {
+  return component.fields[name]?.default;
+}
+
+function componentSchemaTypes(component: { fields: Record<string, { type: string }> }) {
+  return Object.fromEntries(
+    Object.entries(component.fields).map(([name, field]) => [name, field.type]),
+  );
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+type RendererErrorObservation = {
+  readonly code: string;
+  readonly detail?: unknown;
+  readonly hint?: string;
+};
+
+function unwrapRendererError(value: unknown): RendererErrorObservation {
+  let current = value as RendererErrorObservation;
+  while (
+    current.detail !== undefined &&
+    typeof current.detail === 'object' &&
+    current.detail !== null
+  ) {
+    const cause = (current.detail as { cause?: unknown }).cause;
+    if (
+      cause === undefined ||
+      typeof cause !== 'object' ||
+      cause === null ||
+      typeof (cause as { code?: unknown }).code !== 'string'
+    ) {
+      break;
+    }
+    current = cause as RendererErrorObservation;
+  }
+  return current;
+}
+
+function subscribeRendererErrors(
+  renderer: RendererType,
+  listener: (error: RendererErrorObservation) => void,
+): () => void {
+  return renderer.subscribe((event) => {
+    if (event.kind === 'error') listener(unwrapRendererError(event.error));
+  });
+}
+
+function drawPublished(renderer: RendererType, world: WorldType) {
+  const attached = renderer.attach(world);
+  if (!attached.ok) throw attached.error;
+  world.update().unwrap();
+  return drawWithOwners(renderer, world);
+}
+
+// feat-20260704-runtime-tier1-decomposition M2 / w12: reconstitute the
+// eliminated top-level RuntimeErrorCode aggregate union (D-3) as a test-local
+// alias so the exhaustive-switch bodies below stay byte-identical (AC-09).
+type RuntimeLayerErrorCode = RenderErrorCode | AssetRuntimeErrorCode | SkinErrorCode;
+
+import {
+  AnimationTargetId,
+  bindAnimationTargets,
+  advanceAnimationPlayer as canonicalAdvanceAnimationPlayer,
+} from '@forgeax/engine-animation';
+import { deriveAnimationTargetId } from '@forgeax/engine-animation/target-id';
+import { DeviceScope } from '../../../render/src/device/device-scope';
+import { GpuBuffer } from '../../../render/src/gpu-resource';
+import { getOrCreateIblCache, hasIblCache } from '../../../render/src/ibl/IblPipelineCache';
+import {
+  disposeInstanceBuffers,
+  type InstanceBufferCacheEntry,
+} from '../../../render/src/instance-buffer-cache';
+import { standardPipeline as urpPipeline } from '../../../render/src/pipeline/standard-pipeline';
+import { ZERO_CAMERA_CLEAR_FALLBACK } from '../../../render/src/record/frame-snapshot';
+import { warnMultiLightDirectional } from '../../../render/src/record/helpers';
+import type { CameraSnapshot } from '../../../render/src/render-contract';
+import {
+  type ExtractedLights,
+  extractFrame,
+  extractFrames,
+  prepareExtractContext,
+} from '../../../render/src/render-system-extract';
+import {
+  getTransparentSortConfig,
+  setTransparentSortConfig,
+  TRANSPARENT_SORT_CONFIG_KEY,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+} from '../../../render/src/systems/transparent-sort-config';
+import { spriteAnimationTickSystem } from '../systems/sprite-animation-tick';
+import { REC709_LUMA_WEIGHTS, tonemapReinhardLuminance } from '../systems/tonemap';
+import { transparentSortEntries } from '../systems/transparent-sort';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+void [
+  ANTIALIAS_FXAA,
+  ANTIALIAS_NONE,
+  AnimationPlayer,
+  AnimationTargetId,
+  AssetRegistry,
+  BLOOM_DISABLED,
+  BLOOM_ENABLED,
+  CAMERA_PROJECTION_ORTHOGRAPHIC,
+  CAMERA_PROJECTION_PERSPECTIVE,
+  Camera,
+  ChildOf,
+  DeviceScope,
+  ENTITY_NULL_RAW,
+  GpuBuffer,
+  INSTANCE_STORAGE_STRIDE_FLOATS,
+  MeshFilter,
+  MeshRenderer,
+  Name,
+  REC709_LUMA_WEIGHTS,
+  SPRITE_PLAYBACK_MODE_CLAMP,
+  SPRITE_PLAYBACK_MODE_LOOP,
+  Skin,
+  SkinInstancesCoexistForbiddenError,
+  SkinJointCountExceededError,
+  SkinJointDespawnedError,
+  SkinJointPathUnresolvedError,
+  SkyboxBackground,
+  Skylight,
+  SpriteAnimation,
+  SpriteAnimationInvalidError,
+  SpriteRegionOverride,
+  TONEMAP_LUMINANCE_EPSILON,
+  TRANSPARENT_SORT_CONFIG_KEY,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+  Transform,
+  World,
+  ZERO_CAMERA_CLEAR_FALLBACK,
+  afterEach,
+  assembleMaterialWithSkylightEntries,
+  beforeAll,
+  beforeEach,
+  bindAnimationTargets,
+  buildPbrPipelineLayouts,
+  buildUnlitMaterialBgl,
+  cameraProjectionFromF32,
+  canonicalAdvanceAnimationPlayer,
+  componentFieldDefault,
+  componentFieldType,
+  componentSchemaTypes,
+  createSkinPaletteAllocator,
+  createSkylightFallback,
+  deriveAnimationTargetId,
+  describe,
+  disposeInstanceBuffers,
+  drawPublished,
+  drawWithOwners,
+  expect,
+  extractFrame,
+  extractFrames,
+  fileURLToPath,
+  getOrCreateIblCache,
+  getTransparentSortConfig,
+  hasIblCache,
+  it,
+  makeMockShaderRegistry,
+  mat4,
+  mergeSkylightIntoMaterialBgl,
+  prepareExtractContext,
+  propagateTransforms,
+  readFileSync,
+  resolve,
+  rhiOk,
+  selectSwapChainFormat,
+  setTransparentSortConfig,
+  spriteAnimationTickSystem,
+  standardMaterialShaderVariants,
+  subscribeRendererErrors,
+  toShared,
+  tonemapReinhardLuminance,
+  transparentSortEntries,
+  unwrapRendererError,
+  urpPipeline,
+  vec3,
+  vi,
+  warnMultiLightDirectional,
+  worldInternal,
+];
+type __MergedKeep =
+  | AssetRuntimeErrorCode
+  | BindGroupEntry
+  | Buffer
+  | CameraProjection
+  | CameraSnapshot
+  | EntityHandle
+  | ExtractedLights
+  | Handle
+  | InstanceBufferCacheEntry
+  | MaterialAsset
+  | MeshAsset
+  | RenderErrorCode
+  | RendererErrorObservation
+  | RendererType
+  | RuntimeLayerErrorCode
+  | Sampler
+  | SkeletonAsset
+  | SkinErrorCode
+  | Texture
+  | TextureFormat
+  | TextureView
+  | TransparentEntry
+  | WorldType;
+
+{
+  // --- from render-system-record-warn-once.test.ts ---
+
+  function makeFrameState() {
+    return {
+      warnedMultiLightDirectional: false,
+    };
+  }
+
+  describe('warnMultiLightDirectional (M3 / AC-04 / AC-05 (c))', () => {
+    let warnSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+      warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      warnSpy.mockRestore();
+    });
+
+    it('first hit fires console.warn and sets the latch', () => {
+      const fs = makeFrameState();
+      warnMultiLightDirectional(fs, 2);
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(fs.warnedMultiLightDirectional).toBe(true);
+      const call = warnSpy.mock.calls[0];
+      expect(call[0]).toBeTypeOf('string');
+      expect(
+        (call[0] as string).startsWith('[forgeax] render-system-multi-light directional:'),
+      ).toBe(true);
+      expect(call[1]).toMatchObject({
+        code: 'render-system-multi-light',
+        expected: 'at most 1 directional',
+        detail: { type: 'directional', got: 2 },
+      });
+    });
+
+    it('subsequent frames stay silent (warn-once)', () => {
+      const fs = makeFrameState();
+      warnMultiLightDirectional(fs, 2);
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      for (let i = 0; i < 5; i++) {
+        warnMultiLightDirectional(fs, 2);
+      }
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(fs.warnedMultiLightDirectional).toBe(true);
+    });
+
+    it('no-op when directionalCount <= 1 (no fire, latch stays false)', () => {
+      const fs = makeFrameState();
+      warnMultiLightDirectional(fs, 1);
+      warnMultiLightDirectional(fs, 0);
+      expect(warnSpy).toHaveBeenCalledTimes(0);
+      expect(fs.warnedMultiLightDirectional).toBe(false);
+    });
+
+    it('production gate suppresses output but still flips latch', () => {
+      const savedEnv = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process?.env
+        ?.NODE_ENV;
+      try {
+        const fs = makeFrameState();
+        warnMultiLightDirectional(fs, 2, { env: { NODE_ENV: 'production' } });
+        expect(warnSpy).toHaveBeenCalledTimes(0);
+        expect(fs.warnedMultiLightDirectional).toBe(true);
+      } finally {
+        if (savedEnv !== undefined) {
+          const g = globalThis as unknown as { process?: { env?: { NODE_ENV?: string } } };
+          if (!g.process) g.process = {};
+          if (!g.process.env) g.process.env = {};
+          g.process.env.NODE_ENV = savedEnv;
+        }
+      }
+    });
+  });
+}

package/src/__tests__/render-system-record.test.ts

@@ -55,7 +55,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
   // asserts the PBR baseline against literal byte values.
   //
   // Coverage:
-  //   - 384 B payload (STANDARD_PBR_UBO_SIZE)
+  //   - 736 B payload (STANDARD_PBR_UBO_SIZE)
   //   - slot 0 = baseColor.rgb + 1 (alpha hardcoded)
   //   - slot 1 first 8 B = metallic, roughness (f32x2)
   //   - slot 1 last 4 u32 (channelMap) = [2, 1, 0, 0]
@@ -84,9 +84,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
     emissive?: readonly [number, number, number];
     emissiveIntensity?: number;
     occlusionStrength?: number;
-    clearcoat?: number;
-    clearcoatRoughness?: number;
-    specularTint?: readonly [number, number, number];
+    specularColor?: readonly [number, number, number];
   }): MaterialSnapshot {
     return {
       baseColor: opts.baseColor ?? [0.5, 0.6, 0.7, 1],
@@ -97,9 +95,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       ...(opts.emissive !== undefined && { emissive: opts.emissive }),
       ...(opts.emissiveIntensity !== undefined && { emissiveIntensity: opts.emissiveIntensity }),
       ...(opts.occlusionStrength !== undefined && { occlusionStrength: opts.occlusionStrength }),
-      ...(opts.clearcoat !== undefined && { clearcoat: opts.clearcoat }),
-      ...(opts.clearcoatRoughness !== undefined && { clearcoatRoughness: opts.clearcoatRoughness }),
-      ...(opts.specularTint !== undefined && { specularTint: opts.specularTint }),
+      ...(opts.specularColor !== undefined && { specularColor: opts.specularColor }),
     } as unknown as MaterialSnapshot;
   }
 
@@ -108,7 +104,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       expect(typeof mod.buildPbrMaterialUboPayload).toBe('function');
     });
 
-    it('384 B payload size + standard PBR slot layout (baseline)', () => {
+    it('736 B payload size + standard PBR slot layout (baseline)', () => {
       if (typeof mod.buildPbrMaterialUboPayload !== 'function') {
         throw new Error('helper not exported yet');
       }
@@ -119,12 +115,10 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
         emissive: [0, 0, 0],
         emissiveIntensity: 0,
         occlusionStrength: 1,
-        clearcoat: 0.85,
-        clearcoatRoughness: 0.12,
-        specularTint: [0.11, 0.22, 0.33],
+        specularColor: [0.11, 0.22, 0.33],
       });
       const buf = mod.buildPbrMaterialUboPayload(snap);
-      expect(buf.byteLength).toBe(384);
+      expect(buf.byteLength).toBe(736);
       const f32 = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
       // feat-20260613 fix-issue-1 (D-8 channelMap split): the 4 channelMap
       // u32 slots collapse into 4 independent f32 channel selectors at
@@ -154,10 +148,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       expect(f32[16]).toBe(1);
       // alphaCutoff (offset 68).
       expect(f32[17]).toBe(0);
-      // clearcoat layer (offsets 72..79).
-      expect(f32[18]).toBeCloseTo(0.85);
-      expect(f32[19]).toBeCloseTo(0.12);
-      // specularTint vec3 (offsets 80..92).
+      // specularColor vec3 (offsets 80..92; vec3 alignment preserves the slot).
       expect(f32[20]).toBeCloseTo(0.11);
       expect(f32[21]).toBeCloseTo(0.22);
       expect(f32[22]).toBeCloseTo(0.33);
@@ -182,15 +173,12 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       const apply = mod.applyMaterialTextureUvScales;
       if (typeof apply !== 'function') throw new Error('helper not exported yet');
       const world = new World();
-      const pbrPayload = new ArrayBuffer(384);
+      const pbrPayload = new ArrayBuffer(736);
       apply(pbrPayload, makePbrSnapshot({}), world);
       const pbrF32 = new Float32Array(pbrPayload);
-      expect(pbrF32[34]).toBe(1);
-      expect(pbrF32[42]).toBe(1);
-      expect(pbrF32[50]).toBe(1);
-      expect(pbrF32[58]).toBe(1);
-      expect(pbrF32[66]).toBe(1);
-      expect(pbrF32[74]).toBe(1);
+      expect(Array.from(pbrF32.slice(32, 88))).toEqual(
+        Array.from({ length: 7 }, () => [0, 0, 1, 1, 0, 0, 1, 1]).flat(),
+      );
 
       const spritePayload = new ArrayBuffer(128);
       apply(
@@ -1066,9 +1054,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
     { name: 'emissiveIntensity', type: 'f32', default: 0 },
     { name: 'occlusionStrength', type: 'f32', default: 1 },
     { name: 'alphaCutoff', type: 'f32', default: 0 },
-    { name: 'clearcoat', type: 'f32', default: 0 },
-    { name: 'clearcoatRoughness', type: 'f32', default: 0.5 },
-    { name: 'specularTint', type: 'vec3', default: [1, 1, 1] },
+    { name: 'specularColor', type: 'vec3', default: [1, 1, 1] },
   ];
 
   describe('applyParamSnapshotToUbo: standard-pbr byte-identical via derive (M1 / w2)', () => {
@@ -1088,9 +1074,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
       expect(byName.get('emissiveIntensity')?.offset).toBe(60);
       expect(byName.get('occlusionStrength')?.offset).toBe(64);
       expect(byName.get('alphaCutoff')?.offset).toBe(68);
-      expect(byName.get('clearcoat')?.offset).toBe(72);
-      expect(byName.get('clearcoatRoughness')?.offset).toBe(76);
-      expect(byName.get('specularTint')?.offset).toBe(80);
+      expect(byName.get('specularColor')?.offset).toBe(80);
     });
 
     it('generic writer over standard-pbr snapshot equals buildPbrMaterialUboPayload bytes', () => {
@@ -1120,9 +1104,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
         emissiveIntensity,
         occlusionStrength,
         alphaCutoff: 0,
-        clearcoat: 0,
-        clearcoatRoughness: 0.5,
-        specularTint: [1, 1, 1],
+        specularColor: [1, 1, 1],
       } as unknown as MaterialSnapshot;
       const baseline = mod.buildPbrMaterialUboPayload(material);
       // Construct the generic-writer output: start from the same explicit
@@ -1142,7 +1124,7 @@ import { extractFrame, prepareExtractContext } from '../../../render/src/render-
         emissive,
         emissiveIntensity,
         occlusionStrength,
-        specularTint: [1, 1, 1],
+        specularColor: [1, 1, 1],
       };
       mod.applyParamSnapshotToUbo(candidate, STANDARD_PBR_SCHEMA, snapshot);
       expect(new Uint8Array(candidate)).toEqual(new Uint8Array(baseline));

package/src/__tests__/renderer-device-loss-multi-world.integration.test.ts

@@ -0,0 +1,103 @@
+import { World } from '@forgeax/engine-ecs';
+import type { Renderer, RenderWorldLease } from '@forgeax/engine-render';
+import { RhiNullAdapter, rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { constructRendererHost } from '../../../render/src/construct-renderer';
+
+function canvas(): HTMLCanvasElement {
+  return { width: 32, height: 32, getContext: () => null } as unknown as HTMLCanvasElement;
+}
+
+const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+
+function request(
+  leases: readonly RenderWorldLease[],
+  camera: RenderWorldLease,
+  environment: RenderWorldLease,
+) {
+  return { leases, camera: { lease: camera }, environment: { lease: environment } };
+}
+
+describe('M4 / m4_t3 — multi-World recovery keeps logical identities', () => {
+  it('retains World and lease identities when world order changes across recovery', async () => {
+    const adapter = new RhiNullAdapter();
+    const firstDevice = (await adapter.requestDevice()).unwrap();
+    const replacementDevice = (await adapter.requestDevice()).unwrap();
+    let rejectLoss!: (reason: unknown) => void;
+    const lost = new Promise<never>((_, reject) => {
+      rejectLoss = reject;
+    });
+    const lostProxy = new Proxy(firstDevice, {
+      get(target, property) {
+        if (property === 'lost') return lost;
+        const value = Reflect.get(target, property, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+      },
+    });
+    let requestCount = 0;
+    const recoverableRhi = {
+      ...rhi,
+      requestAdapter: async () =>
+        ok({
+          features: adapter.features,
+          limits: adapter.limits,
+          requestDevice: async () => {
+            requestCount += 1;
+            return ok(requestCount === 1 ? lostProxy : replacementDevice);
+          },
+        } as never),
+    } as never;
+    const host = await constructRendererHost(
+      canvas(),
+      { rhi: recoverableRhi },
+      { shaderManifestUrl: manifest },
+    );
+    expect(host.ok).toBe(true);
+    if (!host.ok) return;
+    const renderer: Renderer = host.value.renderer;
+    const firstWorld = new World();
+    const secondWorld = new World();
+    const firstLease = renderer.attach(firstWorld);
+    const secondLease = renderer.attach(secondWorld);
+    expect(firstLease.ok).toBe(true);
+    expect(secondLease.ok).toBe(true);
+    if (!firstLease.ok || !secondLease.ok) return;
+
+    expect(firstWorld.identity).not.toBe(secondWorld.identity);
+    const before = {
+      firstWorld: firstWorld.identity,
+      secondWorld: secondWorld.identity,
+      firstLease: firstLease.value,
+      secondLease: secondLease.value,
+    };
+    expect(
+      renderer.draw(
+        request([firstLease.value, secondLease.value], firstLease.value, secondLease.value),
+      ).ok,
+    ).toBe(true);
+    expect(
+      renderer.draw(
+        request([secondLease.value, firstLease.value], secondLease.value, firstLease.value),
+      ).ok,
+    ).toBe(true);
+    const beforeScene = renderer.inspect().renderScene;
+    rejectLoss({ reason: 'unknown', message: 'forced multi-world device loss' });
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(renderer.state()).toBe('device-lost');
+    const recovered = await renderer.recover();
+    expect(recovered.ok).toBe(true);
+    expect(firstWorld.identity).toBe(before.firstWorld);
+    expect(secondWorld.identity).toBe(before.secondWorld);
+    expect(firstLease.value).toBe(before.firstLease);
+    expect(secondLease.value).toBe(before.secondLease);
+    expect(
+      renderer.draw(
+        request([secondLease.value, firstLease.value], secondLease.value, firstLease.value),
+      ).ok,
+    ).toBe(true);
+    expect(renderer.inspect().renderScene.projectionRecords).toBe(beforeScene.projectionRecords);
+    renderer.dispose();
+  });
+});