@forgeax/engine-render 0.1.23 → 0.1.25

package/src/record/__tests__/sprite-material-abi.unit.test.ts

@@ -1,10 +1,27 @@
 import type { Buffer, Sampler, TextureView } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
 import { assembleMaterialWithSkylightEntries } from '../../ibl/skylight-bind-group';
+import { defaultViewForUserRegionField } from '../main-pass-material';
 import { buildSpritePassBaseMaterialEntries } from '../main-pass-sprite-draws';
 import type { PipelineState } from '../render-context';
 
 describe('sprite Standard material ABI', () => {
+  it('uses the dedicated neutral anisotropy fallback instead of white', () => {
+    const white = {} as TextureView;
+    const anisotropy = {} as TextureView;
+    const pipelineState = {
+      defaultWhiteTextureView: white,
+      defaultAnisotropyTextureView: anisotropy,
+      defaultNormalTextureView: {} as TextureView,
+      fallbackTextureView: {} as TextureView,
+    } as PipelineState;
+
+    expect(defaultViewForUserRegionField('anisotropyTexture', pipelineState)).toBe(anisotropy);
+    expect(defaultViewForUserRegionField('baseColorTexture', pipelineState)).toBe(
+      pipelineState.fallbackTextureView,
+    );
+  });
+
   it('covers transmission and thickness before IBL injection', () => {
     const sampler = {} as Sampler;
     const white = {} as TextureView;
@@ -21,14 +38,12 @@ describe('sprite Standard material ABI', () => {
     const entries = buildSpritePassBaseMaterialEntries(pipelineState, spriteTexture);
 
     expect(entries.map((entry) => entry.binding)).toEqual([
-      0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
+      0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
     ]);
     expect(entries[13]).toMatchObject({ binding: 13, resource: { kind: 'sampler' } });
     expect(entries[14]).toMatchObject({ binding: 14, resource: { kind: 'textureView' } });
-    expect(entries[15]).toMatchObject({ binding: 15, resource: { kind: 'sampler' } });
-    expect(entries[16]).toMatchObject({ binding: 16, resource: { kind: 'textureView' } });
     expect(entries[2]?.resource).toMatchObject({ kind: 'textureView', value: spriteTexture });
-    expect(entries).toHaveLength(17);
+    expect(entries).toHaveLength(15);
 
     const merged = assembleMaterialWithSkylightEntries(entries, {
       irradianceView: {} as TextureView,
@@ -39,19 +54,19 @@ describe('sprite Standard material ABI', () => {
       brdfLutSampler: sampler,
       intensityBuffer: {} as Buffer,
     });
-    expect(merged[17]).toMatchObject({
-      binding: 17,
+    expect(merged[15]).toMatchObject({
+      binding: 15,
       resource: { kind: 'textureView' },
     });
-    expect(merged[24]).toMatchObject({
-      binding: 24,
+    expect(merged[22]).toMatchObject({
+      binding: 22,
       resource: { kind: 'sampler', value: sampler },
     });
-    expect(merged[25]).toMatchObject({
-      binding: 25,
+    expect(merged[23]).toMatchObject({
+      binding: 23,
       resource: { kind: 'textureView' },
     });
-    expect(merged).toHaveLength(26);
+    expect(merged).toHaveLength(24);
 
     const backdrop = {} as TextureView;
     const active = assembleMaterialWithSkylightEntries(
@@ -67,8 +82,8 @@ describe('sprite Standard material ABI', () => {
       },
       { sampler, backdropView: backdrop },
     );
-    expect(active[25]).toMatchObject({
-      binding: 25,
+    expect(active[23]).toMatchObject({
+      binding: 23,
       resource: { kind: 'textureView', value: backdrop },
     });
   });

package/src/record/__tests__/standard-pbr-ubo-layout.unit.test.ts

@@ -14,7 +14,7 @@ describe('Standard PBR UBO layout', () => {
       derived.coordinateRecords.map((record) => [record.parameter, record.offset]),
     );
 
-    expect(derived.totalBytes).toBe(384);
+    expect(derived.totalBytes).toBe(736);
     expect(numeric.get('normalScale')).toBe(92);
     expect(numeric.get('transmission')).toBe(96);
     expect(numeric.get('ior')).toBe(100);
@@ -26,6 +26,26 @@ describe('Standard PBR UBO layout', () => {
     expect(coordinates.get('thicknessTexture')).toBe(352);
   });
 
+  it('reserves the physical-layer tail required by the clearcoat shader ABI', () => {
+    const material = {
+      baseColor: vec3.create(0.7, 0.7, 0.7),
+      metallic: 0,
+      roughness: 0.4,
+      materialShaderId: 'forgeax::default-standard-pbr',
+      materialParamSchema: DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+      paramSnapshot: {
+        clearcoat: 0.8,
+        clearcoatRoughness: 0.2,
+        clearcoatNormalScale: 0.75,
+      },
+    } satisfies MaterialSnapshot;
+    const payload = buildPbrMaterialUboPayload(material);
+    const f32 = new Float32Array(payload.buffer);
+
+    expect(payload.byteLength).toBe(736);
+    expect(f32.slice(108, 111)).toEqual(new Float32Array([0.8, 0.2, 0.75]));
+  });
+
   it('writes transmission scalars and defaults at the reflected offsets', () => {
     const material = {
       baseColor: vec3.create(0.7, 0.7, 0.7),
@@ -33,6 +53,7 @@ describe('Standard PBR UBO layout', () => {
       roughness: 0.4,
       normalScale: 0.25,
       materialShaderId: 'forgeax::default-standard-pbr',
+      materialParamSchema: DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
       paramSnapshot: {
         transmission: 0.75,
         ior: 1.6,
@@ -48,7 +69,7 @@ describe('Standard PBR UBO layout', () => {
     );
   });
 
-  it('uses all eight identity coordinate records in the no-snapshot fallback', () => {
+  it('uses all seven user-region identity coordinate records in the no-snapshot fallback', () => {
     const material = {
       baseColor: vec3.create(0.7, 0.7, 0.7),
       metallic: 0,
@@ -60,8 +81,30 @@ describe('Standard PBR UBO layout', () => {
     applyMaterialTextureUvScales(payload, material, new World());
 
     const f32 = new Float32Array(payload.buffer);
-    expect(f32.slice(32, 96)).toEqual(
-      new Float32Array(Array(8).fill([0, 0, 1, 1, 0, 0, 1, 1]).flat()),
+    expect(f32.slice(32, 88)).toEqual(
+      new Float32Array(Array(7).fill([0, 0, 1, 1, 0, 0, 1, 1]).flat()),
     );
   });
+
+  it('keeps the physical tail intact when standard coordinates are projected', () => {
+    const material = {
+      baseColor: vec3.create(0.7, 0.7, 0.7),
+      metallic: 0,
+      roughness: 0.4,
+      materialShaderId: 'forgeax::default-standard-pbr',
+      materialParamSchema: DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+      paramSnapshot: {
+        clearcoat: 1,
+        clearcoatRoughness: 0.18,
+        clearcoatNormalScale: 0.75,
+      },
+    } satisfies MaterialSnapshot;
+    const payload = buildPbrMaterialUboPayload(material);
+
+    applyMaterialTextureUvScales(payload, material, new World());
+
+    const f32 = new Float32Array(payload.buffer);
+    expect(f32.slice(108, 111)).toEqual(new Float32Array([1, 0.18, 0.75]));
+    expect(f32.slice(32, 40)).toEqual(new Float32Array([0, 0, 1, 1, 0, 0, 1, 1]));
+  });
 });

package/src/record/__tests__/temporal-payload.unit.test.ts

@@ -2,7 +2,7 @@ import { vec3 } from '@forgeax/engine-math';
 import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
 import type { CameraSnapshot } from '../../render-contract';
-import type { RenderableSnapshot, SpotLightSnapshot } from '../../render-system-extract';
+import type { RenderableSnapshot } from '../../render-system-extract';
 import type { TemporalView } from '../../temporal/temporal-view';
 import type { ValidatedRenderable } from '../frame-snapshot';
 import { uploadMeshSsboBatch } from '../mesh-ssbo';
@@ -98,27 +98,8 @@ function temporalView(): TemporalView {
 }
 
 describe('temporal GPU payloads', () => {
-  it('publishes a projector-only SpotLight matrix into the explicit lane-0 contract', () => {
+  it('keeps the zero-directional fallback direction finite and unscaled', () => {
     const { queue, uploads } = recordingQueue();
-    const projectorMatrix = translatedMatrix(9);
-    const projector: SpotLightSnapshot = {
-      kind: 'spot',
-      entity: 4,
-      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.8,
-      castShadow: false,
-      lightViewProj: projectorMatrix,
-      mapSize: 512,
-      nearPlane: 0.1,
-      farPlane: 25,
-      shadowAtlasTile: -1,
-      projectorAsset: { kind: 'texture' } as never,
-    };
     writeViewUbo(
       queue,
       {} as Buffer,
@@ -126,19 +107,20 @@ describe('temporal GPU payloads', () => {
       {
         kind: 'directional',
         direction: vec3.create(0, -1, 0),
-        color: vec3.create(1, 1, 1),
-        intensity: 1,
+        color: vec3.create(0, 0, 0),
+        intensity: 0,
       },
-      { point: [], spot: [projector] } as never,
-      [projector],
-      undefined,
-      0,
+      { point: [], spot: [] } as never,
+      [],
     );
+
     const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
-    expect(payload[132 + 12]).toBe(9);
+    expect(Array.from(payload.slice(16, 19))).toEqual([0, -1, 0]);
+    expect(Array.from(payload.slice(20, 23))).toEqual([0, 0, 0]);
+    expect(Array.from(payload.slice(16, 23)).every(Number.isFinite)).toBe(true);
   });
 
-  it('writes temporal current/previous projection after the spot-light lanes', () => {
+  it('keeps directional orientation independent from light intensity', () => {
     const { queue, uploads } = recordingQueue();
     writeViewUbo(
       queue,
@@ -146,28 +128,20 @@ describe('temporal GPU payloads', () => {
       camera(),
       {
         kind: 'directional',
-        direction: vec3.create(0, -1, 0),
+        direction: vec3.create(0.25, -0.5, 0.75),
         color: vec3.create(1, 1, 1),
-        intensity: 1,
+        intensity: 4,
       },
       { point: [], spot: [] } as never,
       [],
-      temporalView(),
     );
 
     const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
-    expect(payload.length).toBe(240);
-    expect(payload[196]).toBeCloseTo(Math.sqrt(3));
-    expect(payload[212]).toBe(3);
-    expect(payload[228]).toBeCloseTo(0.1);
-    expect(payload[229]).toBe(100);
-    expect(payload[230]).toBe(0);
+    expect(Array.from(payload.slice(16, 19))).toEqual([0.25, -0.5, 0.75]);
   });
 
-  it('keeps the accepted previous camera in the temporal ABI', () => {
+  it('writes temporal current/previous projection after the spot-light lanes', () => {
     const { queue, uploads } = recordingQueue();
-    const acceptedCamera = [7, 8, 9] as const;
-    const temporal = { ...temporalView(), previousCameraPosition: acceptedCamera };
     writeViewUbo(
       queue,
       {} as Buffer,
@@ -180,11 +154,16 @@ describe('temporal GPU payloads', () => {
       },
       { point: [], spot: [] } as never,
       [],
-      temporal as never,
+      temporalView(),
     );
 
     const payload = new Float32Array(uploads[0]?.buffer ?? new ArrayBuffer(0));
-    expect(Array.from(payload.slice(232, 236))).toEqual([...acceptedCamera, 1]);
+    expect(payload.length).toBe(240);
+    expect(payload[196]).toBeCloseTo(Math.sqrt(3));
+    expect(payload[212]).toBe(3);
+    expect(payload[228]).toBeCloseTo(0.1);
+    expect(payload[229]).toBe(100);
+    expect(payload[230]).toBe(0);
   });
 
   it('seeds previousWorld on the first frame and uses the submitted snapshot later', () => {

package/src/record/__tests__/typed-frame-graph-plan.unit.test.ts

@@ -52,7 +52,7 @@ function executeCapture(overrides: CaptureOverrides = {}) {
         usage: GPU_TEXTURE_USAGE_COPY_SRC,
         identity: overrides.identity ?? {
           graphGeneration: 7,
-          frameId: 12,
+          frameId: 13,
           textureIdentity: getTextureIdentity(texture),
         },
       },

package/src/record/frame-snapshot.ts

@@ -18,6 +18,8 @@ import type { DirectionalShadowQuality } from '../components/directional-shadow-
 import type { EnvironmentGeneration } from '../environment/generation';
 import type { EnvironmentLifecycle } from '../environment/lifecycle';
 import type { GpuBuffer } from '../gpu-resource';
+import type { InstanceCollectionId, InstanceResidency } from '../instances';
+import type { IblBindingInspection } from '../mesh-material-bindings';
 import type { StandardLightingInspection } from '../pipeline/standard-lighting/inspection';
 import type { PointShadowInspection } from '../point-shadow-inspection';
 import type { TemporalGpuState } from '../temporal/gpu';
@@ -51,6 +53,17 @@ export function worldEntityKey(worldId: number, entityKey: number): number {
   return worldId * 4294967296 + entityKey; // 2^32 = 4294967296
 }
 
+/** Per-renderer projection identity, with entity keys for sprite/fold snapshots. */
+export function instanceCollectionCacheKey(
+  worldId: number,
+  instance: { readonly cacheKey: number; readonly collectionId?: number },
+): number {
+  // Keep collection entries in a disjoint numeric namespace from the shared
+  // legacy sprite/fold cache. Fold keys occupy -1..-(2^32), while ordinary
+  // world/entity keys are non-negative; this range starts below both.
+  return -(0x1_0000_0000 + worldEntityKey(worldId, instance.collectionId ?? instance.cacheKey));
+}
+
 /**
  * Cross-frame cache entry for a material bind group whose source material and
  * all resolved GPU resources are stable. The material snapshot identity is
@@ -138,6 +151,18 @@ export interface CurrentGraphTarget {
 const textureIdentities = new WeakMap<object, number>();
 let nextTextureIdentity = 1;
 
+const opaqueResourceIdentities = new WeakMap<object, number>();
+let nextOpaqueResourceIdentity = 1;
+
+/** Stable detached identity for a renderer-owned opaque resource handle. */
+export function getOpaqueResourceIdentity(resource: object): number {
+  const existing = opaqueResourceIdentities.get(resource);
+  if (existing !== undefined) return existing;
+  const identity = nextOpaqueResourceIdentity++;
+  opaqueResourceIdentities.set(resource, identity);
+  return identity;
+}
+
 /**
  * Project an opaque RHI texture handle to a stable diagnostic identity.
  * RHI handles intentionally expose no serializable fields; object identity is
@@ -276,8 +301,9 @@ export function makeZeroCameraFallbackSnapshot(): CameraSnapshot {
  * Owned by the `createRenderSystem` closure; advanced once per
  * `recordFrame` invocation. The `instanceBuffers` map holds the per-entity
  * GPU storage buffers for Instances-bearing entities (cache key = the
- * packed Entity u32 surfaced via `InstancesSnapshot.cacheKey`); entries
- * are recreated when the `archVersion` bumps or `byteLength` changes.
+ * renderer-owned collection id, with the packed Entity u32 retained only for
+ * legacy snapshots); entries are recreated when the `archVersion` bumps or
+ * `byteLength` changes.
  *
  * feat-20260518-pbr-direct-lighting-mvp M3 / w14 (AC-17 a): the
  * `warnedZeroLightStandard` flag latches the first-frame warning that
@@ -289,6 +315,8 @@ export function makeZeroCameraFallbackSnapshot(): CameraSnapshot {
  */
 export interface RenderFrameState {
   frameNumber: number;
+  /** Final-submit Standard IBL binding-chain receipt for this frame. */
+  iblBindingInspection?: IblBindingInspection;
   /** Demand for the frame-local Standard fallback MRT. */
   reflectionFallbackDemand?: boolean;
   /** Monotonic compiled-graph identity used by diagnostic readbacks. */
@@ -375,6 +403,10 @@ export interface RenderFrameState {
   currentDirectionalShadowView: TextureView | null;
   currentSpotShadowView: TextureView | null;
   readonly instanceBuffers: Map<number, InstanceBufferCacheEntry>;
+  /** Renderer-owned collection owner used for record-stage residency facts. */
+  readonly instanceResidency?: Map<InstanceCollectionId, InstanceResidency>;
+  /** Stable buffers for renderer-owned collections split by device cap. */
+  readonly instanceBufferChunks?: Map<string, InstanceBufferCacheEntry>;
   /** Per-object ProbeBlendRecord buffers; upload is one atomic 160B write. */
   readonly probeBlendBuffers: Map<number, ProbeBlendBufferCacheEntry>;
   /** One renderer-owned record array; each object selects its 256B-aligned lane. */

package/src/record/frame-targets.ts

@@ -75,9 +75,19 @@ export function acquireSwapChainTarget(
 
   let currentTextureResult = canvasContext.getCurrentTexture();
   if (!currentTextureResult.ok) {
+    const configuredDevice = internals.resolveSurfaceDevice?.(internals.device);
+    if (configuredDevice !== undefined && !configuredDevice.ok) {
+      internals.errorRegistry.fire(configuredDevice.error);
+      internals.healthRegistry.fire({
+        reason: 'internal-fault',
+        detail: { message: 'surface device resolution failed; current frame skipped' },
+        recoverable: true,
+      });
+      return null;
+    }
     const configured = configureSurface(
       canvasContext,
-      internals.device,
+      configuredDevice?.value ?? internals.device,
       pipelineState.format,
       pipelineState.colorAttachmentFormat,
     );

package/src/record/frame.ts

@@ -86,6 +86,7 @@ import {
   type DispatchCounts,
   type FrameObservationSource,
   getTextureIdentity,
+  instanceCollectionCacheKey,
   makeZeroCameraFallbackSnapshot,
   type ReflectionFallbackReadbackRequest,
   type RenderFrameState,
@@ -2484,7 +2485,7 @@ function prepareDirectionalShadowCache(
  *
  * @internal
  */
-function validateRenderables(
+export function validateRenderables(
   internals: RenderSystemInternals,
   world: World,
   // feat-20260709-editor-world-partition ENGINE-fix-round2 (defect 2): the full
@@ -2714,8 +2715,12 @@ function prepareMorphMesh(
       frameState.morphBuffers.delete(cacheKey);
       return undefined;
     }
+    const buffer = new GpuBuffer(internals.device, created.value);
+    internals.deviceScope._adopt('buffer', buffer, (owned) => {
+      if (!owned.isDestroyed) owned.destroy();
+    });
     cached = {
-      buffer: new GpuBuffer(internals.device, created.value),
+      buffer,
       byteLength: vertices.byteLength,
     };
     frameState.morphBuffers.set(cacheKey, cached);
@@ -2989,8 +2994,14 @@ function cleanPerFrameCaches(
   // composites matching the write-side keys of #1-#3 — cross-world false eviction
   // is prevented because worldEntityKey(0, k) !== worldEntityKey(1, k).
   const validatedEntityKeys = new Set<number>(retainedEntityKeys);
+  const validatedInstanceKeys = new Set<number>(retainedEntityKeys);
   for (const v of validated) {
-    validatedEntityKeys.add(worldEntityKey(v.source.worldId, v.source.entityKey));
+    const entityKey = worldEntityKey(v.source.worldId, v.source.entityKey);
+    validatedEntityKeys.add(entityKey);
+    validatedInstanceKeys.add(entityKey);
+    if (v.source.instances !== undefined) {
+      validatedInstanceKeys.add(instanceCollectionCacheKey(v.source.worldId, v.source.instances));
+    }
   }
 
   // Clean per-entity material BG cache: drop outer-Map entries whose
@@ -3014,7 +3025,7 @@ function cleanPerFrameCaches(
   // material-handle-based and cross-world collision is semantically
   // correct (same material renders in same fold bucket).
   for (const [key, entry] of frameState.instanceBuffers.entries()) {
-    if (!validatedEntityKeys.has(key)) {
+    if (!validatedInstanceKeys.has(key)) {
       if (!entry.buffer.isDestroyed) {
         const r = entry.buffer.destroy();
         if (!r.ok) internals.errorRegistry.fire(r.error);
@@ -3023,6 +3034,28 @@ function cleanPerFrameCaches(
     }
   }
 
+  if (frameState.instanceResidency !== undefined) {
+    const liveCollections = new Set(validated.map((entry) => entry.source.instances?.collectionId));
+    for (const id of frameState.instanceResidency.keys()) {
+      if (!liveCollections.has(id)) frameState.instanceResidency.delete(id);
+    }
+  }
+
+  // Chunk keys are `${worldEntityKey}:${chunkStart}`. Keep the key opaque to
+  // the authoring API, but retain the numeric owner prefix for eviction.
+  if (frameState.instanceBufferChunks !== undefined) {
+    for (const [key, entry] of frameState.instanceBufferChunks.entries()) {
+      const separator = key.indexOf(':');
+      const ownerKey = separator < 0 ? Number.NaN : Number(key.slice(0, separator));
+      if (validatedInstanceKeys.has(ownerKey)) continue;
+      if (!entry.buffer.isDestroyed) {
+        const r = entry.buffer.destroy();
+        if (!r.ok) internals.errorRegistry.fire(r.error);
+      }
+      frameState.instanceBufferChunks.delete(key);
+    }
+  }
+
   if (frameState.morphBuffers !== undefined) {
     for (const [key, entry] of frameState.morphBuffers.entries()) {
       if (validatedEntityKeys.has(key)) continue;

package/src/record/helpers.ts

@@ -214,8 +214,8 @@ export function computeProjectionMatrix(camera: CameraSnapshot): Mat4 {
       proj,
       camera.orthoLeft,
       camera.orthoRight,
-      camera.orthoBottom,
       camera.orthoTop,
+      camera.orthoBottom,
       camera.near,
       camera.far,
     );