@forgeax/engine-render 0.1.21 → 0.1.23

package/src/__tests__/temporal-view.unit.test.ts

@@ -132,7 +132,7 @@ describe('TemporalView v1', () => {
     } as unknown as ExtractedLights;
     const buffer = {} as Parameters<typeof writeViewUbo>[1];
     const first = createTemporalView({ antialias: 'taa', width: 4, height: 4, frameIndex: 0 });
-    writeViewUbo(queue, buffer, camera, light, lights, [], undefined, first);
+    writeViewUbo(queue, buffer, camera, light, lights, [], first);
     expect(Array.from(uploads[0]?.slice(212, 228) ?? [])).toEqual(new Array(16).fill(0));
 
     const previous = Float32Array.from({ length: 16 }, (_value, index) => index + 1);
@@ -143,10 +143,10 @@ describe('TemporalView v1', () => {
       frameIndex: 1,
       previousUnjitteredViewProjection: previous,
     });
-    writeViewUbo(queue, buffer, camera, light, lights, [], undefined, second);
+    writeViewUbo(queue, buffer, camera, light, lights, [], second);
     expect(Array.from(uploads[1]?.slice(212, 228) ?? [])).toEqual(Array.from(previous));
 
-    writeViewUbo(queue, buffer, camera, light, lights, [], undefined, second);
+    writeViewUbo(queue, buffer, camera, light, lights, [], second);
     expect(Array.from(uploads[2]?.slice(212, 228) ?? [])).toEqual(Array.from(previous));
   });
 });

package/src/__tests__/transmission-prewarm.unit.test.ts

@@ -13,6 +13,10 @@ const hdrpFalseKey =
   'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=false';
 const hdrpTrueKey =
   'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
+const probeFalseKey =
+  'CLUSTER_FORWARD_AVAILABLE=false+PROBE_BLEND_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=false';
+const probeTrueKey =
+  'CLUSTER_FORWARD_AVAILABLE=false+PROBE_BLEND_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
 
 function standardEntry(
   variants: readonly MaterialShaderManifestEntry['variants'][number][],
@@ -52,6 +56,33 @@ function hdrpVariant(definesKey: string, transmission: boolean) {
   };
 }
 
+function probeTransmissionVariant(definesKey: string, transmission: boolean) {
+  const base = transmissionVariant(definesKey, transmission);
+  return {
+    ...base,
+    definesKey,
+    defines: { ...base.defines, PROBE_BLEND_AVAILABLE: true },
+  };
+}
+
+function capabilityTransmissionVariant(
+  definesKey: string,
+  transmission: boolean,
+  extendedLighting: boolean,
+) {
+  const base = transmissionVariant(definesKey, transmission);
+  return {
+    ...base,
+    definesKey,
+    defines: {
+      ...base.defines,
+      EXTENDED_LIGHTING_AVAILABLE: extendedLighting,
+      PROJECTOR_AVAILABLE: true,
+    },
+    composedWgsl: `standard-${extendedLighting ? 'extended' : 'fallback'}-${transmission}`,
+  };
+}
+
 describe('Standard transmission exact-key prewarm selection', () => {
   it('returns both declared variants through exact manifest lookup', () => {
     const entry = standardEntry([
@@ -74,6 +105,44 @@ describe('Standard transmission exact-key prewarm selection', () => {
       'manifest row is missing',
     );
   });
+
+  it('keeps object-level probe variants out of the boot prewarm selection', () => {
+    const entry = standardEntry([
+      probeTransmissionVariant(probeFalseKey, false),
+      transmissionVariant(falseKey, false),
+      probeTransmissionVariant(probeTrueKey, true),
+      transmissionVariant(trueKey, true),
+    ]);
+    expect(
+      selectStandardPbrTransmissionPrewarmVariants(entry, true).map(
+        (variant) => variant.definesKey,
+      ),
+    ).toEqual([falseKey, trueKey]);
+  });
+
+  it('selects the prewarm pair for the admitted extended-lighting capability', () => {
+    const fallbackFalseKey = `${falseKey}+EXTENDED_LIGHTING_AVAILABLE=false+PROJECTOR_AVAILABLE=true`;
+    const fallbackTrueKey = `${trueKey}+EXTENDED_LIGHTING_AVAILABLE=false+PROJECTOR_AVAILABLE=true`;
+    const extendedFalseKey = `${falseKey}+EXTENDED_LIGHTING_AVAILABLE=true+PROJECTOR_AVAILABLE=true`;
+    const extendedTrueKey = `${trueKey}+EXTENDED_LIGHTING_AVAILABLE=true+PROJECTOR_AVAILABLE=true`;
+    const entry = standardEntry([
+      capabilityTransmissionVariant(fallbackFalseKey, false, false),
+      capabilityTransmissionVariant(fallbackTrueKey, true, false),
+      capabilityTransmissionVariant(extendedFalseKey, false, true),
+      capabilityTransmissionVariant(extendedTrueKey, true, true),
+    ]);
+
+    expect(
+      selectStandardPbrTransmissionPrewarmVariants(entry, true, true, true, false).map(
+        (variant) => variant.definesKey,
+      ),
+    ).toEqual([fallbackFalseKey, fallbackTrueKey]);
+    expect(
+      selectStandardPbrTransmissionPrewarmVariants(entry, true, true, true, true).map(
+        (variant) => variant.definesKey,
+      ),
+    ).toEqual([extendedFalseKey, extendedTrueKey]);
+  });
 });
 
 describe('HDRP PBR prewarm capability selection', () => {

package/src/__tests__/visibility-budget.integration.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from 'vitest';
+import { createVisibilityBudget } from '../scene/visibility/budget';
+import {
+  primitiveKey,
+  primitiveKeyId,
+  VisibilityFacetStore,
+  viewKey,
+  viewKeyId,
+} from '../scene/visibility/facet';
+
+const view = (cameraEntity: number) =>
+  viewKey({
+    attachmentId: 'budget-scene',
+    cameraEntity,
+    viewRole: 'main',
+    viewGeneration: 1,
+  });
+
+const primitive = (slot: number) =>
+  primitiveKey({
+    attachmentId: 'budget-scene',
+    worldGeneration: 1,
+    primitiveSlot: slot,
+    slotGeneration: 1,
+  });
+
+describe('visibility budget integration', () => {
+  it('shares one derived window across views and LOD levels', () => {
+    const budget = createVisibilityBudget(2048);
+    const facets = new VisibilityFacetStore(budget);
+    const views = [view(1), view(2)];
+    for (const currentView of views) {
+      facets.activateView(currentView);
+      for (let level = 0; level < 8; level += 1) {
+        const currentPrimitive = primitive(currentView.cameraEntity * 10 + level);
+        facets.setCandidate(currentView, currentPrimitive, { level, confidence: 1 });
+        facets.applyConfidence(currentView, currentPrimitive, {
+          type: 'result',
+          samples: 0,
+          submissionGeneration: 1,
+        });
+        facets.applyConfidence(currentView, currentPrimitive, {
+          type: 'result',
+          samples: 0,
+          submissionGeneration: 2,
+        });
+      }
+    }
+
+    expect(facets.visibilityBudget()).toBe(budget);
+    expect(facets.visibilityBudget()).toMatchObject({
+      effectiveQueryBudget: 2048,
+      settleSubmits: 98,
+      retestSubmits: 44,
+      expirySubmits: 88,
+    });
+
+    facets.advanceSuccessfulSubmits(2 + budget.retestSubmits);
+    for (const currentView of views) {
+      expect(facets.shouldQuery(currentView, primitive(currentView.cameraEntity * 10))).toBe(true);
+    }
+  });
+
+  it('keeps invalidation visible and requeues the same identity without extending evidence', () => {
+    const budget = createVisibilityBudget(4096);
+    const facets = new VisibilityFacetStore(budget);
+    const currentView = view(3);
+    const currentPrimitive = primitive(3);
+    facets.activateView(currentView);
+    facets.setCandidate(currentView, currentPrimitive, { level: 2, confidence: 1 });
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 1,
+    });
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 2,
+    });
+    facets.advanceSuccessfulSubmits(2 + budget.retestSubmits, [
+      { view: currentView, primitive: currentPrimitive },
+    ]);
+    expect(facets.getConfidence(currentView, currentPrimitive).status).toBe('hidden');
+
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'invalidate',
+      reason: 'world-reorder',
+    });
+    expect(facets.getConfidence(currentView, currentPrimitive)).toMatchObject({
+      status: 'visible',
+      dirty: true,
+      queryable: true,
+    });
+    expect(facets.dequeueQueryCandidates(currentView, 1)).toHaveLength(1);
+  });
+
+  it('uses expiry-only scheduling for a due hidden row while its query is in flight', () => {
+    const budget = createVisibilityBudget();
+    const facets = new VisibilityFacetStore(budget);
+    const currentView = view(4);
+    const currentPrimitive = primitive(4);
+    facets.activateView(currentView);
+    facets.setCandidate(currentView, currentPrimitive, { level: 0, confidence: 1 });
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 1,
+    });
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'result',
+      samples: 0,
+      submissionGeneration: 2,
+    });
+    const dueGeneration = 2 + budget.retestSubmits;
+    facets.advanceSuccessfulSubmits(dueGeneration);
+    expect(facets.dequeueQueryCandidates(currentView, 1)).toHaveLength(1);
+
+    facets.applyConfidence(currentView, currentPrimitive, {
+      type: 'submit',
+      submissionGeneration: dueGeneration,
+    });
+    expect(facets.getConfidence(currentView, currentPrimitive).successfulSubmits).toBe(
+      budget.retestSubmits + 1,
+    );
+    const scheduler = facets as unknown as {
+      confidence: { wakeByGeneration: Map<number, Set<string>> };
+    };
+    const key = `${viewKeyId(currentView)}|${primitiveKeyId(currentPrimitive)}`;
+    expect([...scheduler.confidence.wakeByGeneration.values()].flat()).not.toContain(key);
+
+    facets.advanceSuccessfulSubmits(
+      dueGeneration + budget.expirySubmits - budget.retestSubmits - 1,
+    );
+    expect(facets.getConfidence(currentView, currentPrimitive)).toMatchObject({
+      status: 'visible',
+      dirty: true,
+    });
+  });
+});

package/src/__tests__/visibility-budget.unit.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createVisibilityBudget,
+  DEFAULT_CONFIGURED_QUERY_BUDGET,
+  MAX_QUERY_BUDGET,
+} from '../scene/visibility/budget';
+
+describe('visibility budget derivation', () => {
+  it.each([
+    [
+      2048,
+      {
+        effectiveQueryBudget: 2048,
+        oneSweepCandidates: 49,
+        oneSweepOccluded: 44,
+        settleSubmits: 98,
+        retestSubmits: 44,
+        expirySubmits: 88,
+      },
+    ],
+    [
+      4096,
+      {
+        effectiveQueryBudget: 4096,
+        oneSweepCandidates: 25,
+        oneSweepOccluded: 22,
+        settleSubmits: 50,
+        retestSubmits: 22,
+        expirySubmits: 44,
+      },
+    ],
+  ])('derives the approved windows for Q=%d', (configuredQueryBudget, expected) => {
+    expect(createVisibilityBudget(configuredQueryBudget)).toMatchObject({
+      configuredQueryBudget,
+      ...expected,
+    });
+  });
+
+  it('uses the default and clamps larger configured budgets without changing page policy', () => {
+    expect(createVisibilityBudget()).toMatchObject({
+      configuredQueryBudget: DEFAULT_CONFIGURED_QUERY_BUDGET,
+      effectiveQueryBudget: DEFAULT_CONFIGURED_QUERY_BUDGET,
+    });
+    expect(createVisibilityBudget(MAX_QUERY_BUDGET + 1).effectiveQueryBudget).toBe(
+      MAX_QUERY_BUDGET,
+    );
+  });
+
+  it.each([
+    0,
+    -1,
+    1.5,
+    Number.NaN,
+    Number.POSITIVE_INFINITY,
+  ])('rejects invalid configured budget %s', (configuredQueryBudget) => {
+    expect(() => createVisibilityBudget(configuredQueryBudget)).toThrow(
+      'configuredQueryBudget must be a positive safe integer',
+    );
+  });
+
+  it.each([1, 2, 3, 4, 8])('keeps derived windows independent of %d LOD levels', (levels) => {
+    const budget = createVisibilityBudget(2048);
+    expect({ levels, ...budget }).toMatchObject({
+      levels,
+      settleSubmits: 98,
+      retestSubmits: 44,
+      expirySubmits: 88,
+    });
+  });
+});

package/src/__tests__/visibility-extract.integration.test.ts

@@ -1,5 +1,10 @@
 import { World } from '@forgeax/engine-ecs';
-import { ChildOf, registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import {
+  ChildOf,
+  GlobalTransform,
+  registerPropagateTransforms,
+  Transform,
+} from '@forgeax/engine-scene';
 import { describe, expect, it, vi } from 'vitest';
 import { Fog } from '../components/fog';
 import { Visibility, VisibilityStateValue } from '../components/visibility';
@@ -67,13 +72,13 @@ describe('visibility extract orchestration', () => {
     const snapshot = frame.visibilitySnapshots[0];
     expect(snapshot?.get(parent)?.effective).toBe('visible');
     expect(snapshot?.get(child)?.effective).toBe('visible');
-    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(3);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(3);
   });
 
-  it('keeps renderer extraction read-only over derived Transform.world', () => {
+  it('keeps renderer extraction read-only over derived GlobalTransform.world', () => {
     const { world, parent, child } = makeWorld();
     world.update(0).unwrap();
-    const before = [...world.get(child, Transform).unwrap().world];
+    const before = [...world.get(child, GlobalTransform).unwrap().world];
     const beforeInspection = world.inspect();
     const beforeShape = {
       entityCount: beforeInspection.entityCount,
@@ -87,7 +92,7 @@ describe('visibility extract orchestration', () => {
     world.set(parent, Transform, { pos: [9, 0, 0] }).unwrap();
     extractFrames([world], 0);
 
-    expect([...world.get(child, Transform).unwrap().world]).toEqual(before);
+    expect([...world.get(child, GlobalTransform).unwrap().world]).toEqual(before);
     const afterInspection = world.inspect();
     expect({
       entityCount: afterInspection.entityCount,
@@ -98,7 +103,7 @@ describe('visibility extract orchestration', () => {
       resourceKeys: afterInspection.resourceKeys,
     }).toEqual(beforeShape);
     world.update(0).unwrap();
-    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(11);
+    expect(world.get(child, GlobalTransform).unwrap().world[12]).toBeCloseTo(11);
   });
 
   it('keeps direct prepared-kernel output aligned with extractFrames output', () => {

package/src/__tests__/volumetric-fog-point-spot-accumulation.integration.test.ts

@@ -13,8 +13,10 @@ const passes = readFileSync(new URL('../volume/passes.ts', import.meta.url), 'ut
 
 describe('volumetric fog Point and Spot accumulation', () => {
   it('accumulates Point and Spot in one fixed inject stage', () => {
-    expect(inject).toContain('pointLightsBuffer');
-    expect(inject).toContain('spotLightsBuffer');
+    expect(inject).toContain('light_data');
+    expect(inject).toContain('cluster_uniform');
+    expect(inject).not.toContain('pointLightsBuffer');
+    expect(inject).not.toContain('spotLightsBuffer');
     expect(inject).toContain('evalVolumePoint');
     expect(inject).toContain('evalVolumeSpot');
     expect(inject).toContain('shadow_visibility');
@@ -37,7 +39,8 @@ describe('volumetric fog Point and Spot accumulation', () => {
   });
 
   it('retains falsifier hooks for off lights, occluders, and shadow visibility', () => {
-    expect(inject).toContain('count');
+    expect(inject).toContain('selected_cluster_light_slot');
+    expect(inject).toContain('cluster_uniform.grid.w');
     expect(inject).toContain('shadowAtlasTile');
     expect(inject).toContain('return 0.0');
     expect(integrate).toContain('evalSpotAttenuation');

package/src/__tests__/volumetric-fog-stage-readback.dawn.test.ts

@@ -2,12 +2,7 @@ import type { RhiDevice, Texture, TextureView } from '@forgeax/engine-rhi';
 import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
 import { buildEngineShaderManifest } from '@forgeax/engine-vite-plugin-shader';
 import { describe, expect, it } from 'vitest';
-import {
-  LIGHT_ARRAY_HEADER_BYTES,
-  LIGHT_ARRAY_MAX_SLOTS,
-  POINT_LIGHT_STD430_BYTES,
-  SPOT_LIGHT_STD430_BYTES,
-} from '../light-buffer-layout';
+import { BYTES_PER_DIRECT_LIGHT_SLOT } from '../light-buffer-layout';
 
 const MAP_READ = 0x0001;
 const BUFFER_COPY_DST = 0x0008;
@@ -21,6 +16,9 @@ const SIZE = 8;
 const PACKED_LAYERS = Math.ceil(SIZE / 4);
 const BYTES_PER_ROW = 256;
 const BYTES_PER_PIXEL = 8;
+const MAX_CLUSTER_LIGHTS = 256;
+const CLUSTER_LIGHT_DATA_BYTES = MAX_CLUSTER_LIGHTS * BYTES_PER_DIRECT_LIGHT_SLOT;
+const CLUSTER_UNIFORM_BYTES = 32;
 const engineManifest = await buildEngineShaderManifest();
 
 interface StageValues {
@@ -190,15 +188,15 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
     size: 128,
     usage: 0x0040 | BUFFER_COPY_DST,
   });
-  const spotLightsBuffer = device.createBuffer({
-    label: 'stage-readback.spot-lights',
-    size: LIGHT_ARRAY_HEADER_BYTES + LIGHT_ARRAY_MAX_SLOTS * SPOT_LIGHT_STD430_BYTES,
+  const lightDataBuffer = device.createBuffer({
+    label: 'stage-readback.cluster-light-data',
+    size: CLUSTER_LIGHT_DATA_BYTES,
     usage: STORAGE_BUFFER | BUFFER_COPY_DST,
   });
-  const pointLightsBuffer = device.createBuffer({
-    label: 'stage-readback.point-lights',
-    size: LIGHT_ARRAY_HEADER_BYTES + LIGHT_ARRAY_MAX_SLOTS * POINT_LIGHT_STD430_BYTES,
-    usage: STORAGE_BUFFER | BUFFER_COPY_DST,
+  const clusterUniformBuffer = device.createBuffer({
+    label: 'stage-readback.cluster-uniform',
+    size: CLUSTER_UNIFORM_BYTES,
+    usage: 0x0040 | BUFFER_COPY_DST,
   });
   const injectReadback = device.createBuffer({
     label: 'stage-readback.inject',
@@ -218,8 +216,8 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
   if (
     !viewBuffer.ok ||
     !paramsBuffer.ok ||
-    !spotLightsBuffer.ok ||
-    !pointLightsBuffer.ok ||
+    !lightDataBuffer.ok ||
+    !clusterUniformBuffer.ok ||
     !injectReadback.ok ||
     !temporalReadback.ok ||
     !integrateReadback.ok
@@ -245,19 +243,22 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
   paramsData.set([0, -1, 0, 0], 20);
   paramsData.set([1, 1, 1, 0], 24);
   paramsData.set([2, 0, 0, 0], 28);
+  const lightData = new Uint8Array(CLUSTER_LIGHT_DATA_BYTES);
+  const clusterUniformData = new Float32Array(8);
+  const clusterGrid = new Uint32Array(clusterUniformData.buffer);
+  clusterGrid[0] = 1;
+  clusterGrid[1] = 1;
+  clusterGrid[2] = 1;
+  clusterGrid[3] = 1;
   const viewWrite = device.queue.writeBuffer(viewBuffer.value, 0, viewData);
   const paramsWrite = device.queue.writeBuffer(paramsBuffer.value, 0, paramsData);
-  const spotLightsWrite = device.queue.writeBuffer(
-    spotLightsBuffer.value,
-    0,
-    new Uint32Array([0, 0, 0, 0]),
-  );
-  const pointLightsWrite = device.queue.writeBuffer(
-    pointLightsBuffer.value,
+  const lightDataWrite = device.queue.writeBuffer(lightDataBuffer.value, 0, lightData);
+  const clusterUniformWrite = device.queue.writeBuffer(
+    clusterUniformBuffer.value,
     0,
-    new Uint32Array([0, 0, 0, 0]),
+    clusterUniformData,
   );
-  if (!viewWrite.ok || !paramsWrite.ok || !spotLightsWrite.ok || !pointLightsWrite.ok)
+  if (!viewWrite.ok || !paramsWrite.ok || !lightDataWrite.ok || !clusterUniformWrite.ok)
     throw new Error('Dawn volume stage readback unavailable: uniform upload failed');
   const densityData = new Uint8Array((BYTES_PER_PIXEL / 2) * SIZE * SIZE * SIZE);
   densityData.fill(255);
@@ -291,6 +292,7 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
         storageTexture: { access: 'write-only', format: 'rgba8unorm', viewDimension: '2d-array' },
       },
       { binding: 7, visibility: 4, buffer: { type: 'read-only-storage' } },
+      { binding: 8, visibility: 4, buffer: { type: 'uniform' } },
     ],
   });
   if (!layout.ok) throw layout.error;
@@ -354,7 +356,7 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
         storageTexture: { access: 'write-only', format: 'rgba16float', viewDimension: '2d' },
       },
       { binding: 10, visibility: 4, buffer: { type: 'read-only-storage' } },
-      { binding: 11, visibility: 4, buffer: { type: 'read-only-storage' } },
+      { binding: 11, visibility: 4, buffer: { type: 'uniform' } },
       { binding: 12, visibility: 4, texture: { sampleType: 'float', viewDimension: '2d' } },
       { binding: 13, visibility: 4, sampler: { type: 'filtering' } },
     ],
@@ -393,7 +395,8 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
       { binding: 4, resource: { kind: 'sampler', value: comparisonSampler.value } },
       { binding: 5, resource: { kind: 'buffer', value: { buffer: paramsBuffer.value } } },
       { binding: 6, resource: { kind: 'textureView', value: outputView } },
-      { binding: 7, resource: { kind: 'buffer', value: { buffer: spotLightsBuffer.value } } },
+      { binding: 7, resource: { kind: 'buffer', value: { buffer: lightDataBuffer.value } } },
+      { binding: 8, resource: { kind: 'buffer', value: { buffer: clusterUniformBuffer.value } } },
     ],
   });
   if (!bindings.ok) throw bindings.error;
@@ -420,8 +423,8 @@ async function runInjectReadback(sceneDepthClear = 1): Promise<VolumeStageReadba
       { binding: 7, resource: { kind: 'sampler', value: densitySampler.value } },
       { binding: 8, resource: { kind: 'textureView', value: historyView } },
       { binding: 9, resource: { kind: 'textureView', value: temporalView } },
-      { binding: 10, resource: { kind: 'buffer', value: { buffer: spotLightsBuffer.value } } },
-      { binding: 11, resource: { kind: 'buffer', value: { buffer: pointLightsBuffer.value } } },
+      { binding: 10, resource: { kind: 'buffer', value: { buffer: lightDataBuffer.value } } },
+      { binding: 11, resource: { kind: 'buffer', value: { buffer: clusterUniformBuffer.value } } },
       { binding: 12, resource: { kind: 'textureView', value: projectorView } },
       { binding: 13, resource: { kind: 'sampler', value: densitySampler.value } },
     ],

package/src/assembly/backend-contract.ts

@@ -10,6 +10,19 @@ import type {
 /** Optional host hooks for recorder and device-lifecycle capabilities. */
 export interface RhiBackendInstrumentation {
   readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
+  /**
+   * Optional deterministic submit fault seam for backend-owned integration
+   * fixtures. The callback runs after `finish()` and before the queue submit;
+   * returning an error aborts the frame transaction without changing the
+   * production queue contract.
+   */
+  readonly beforeSubmit?: (device: RhiDevice) => RhiError | undefined;
+  /**
+   * Optional device-loss projection for deterministic recovery fixtures. A
+   * backend may compose this promise with its native `device.lost` promise;
+   * normal production packs leave it undefined and use the native signal.
+   */
+  readonly deviceLost?: (device: RhiDevice) => RhiDevice['lost'];
   readonly onFrameBoundary?: () => void;
   readonly onDeviceLost?: () => void;
 }

package/src/assembly/device-feature-admission.ts

@@ -1,4 +1,5 @@
 import type { RhiAdapter, RhiDevice } from '@forgeax/engine-rhi';
+import { EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES } from '../prepare/extended-lighting/resources';
 
 const COMPRESSION_FEATURES: GPUFeatureName[] = [
   'texture-compression-bc',
@@ -9,7 +10,9 @@ const COMPRESSION_FEATURES: GPUFeatureName[] = [
 // The Standard transmission fragment ABI needs 17 sampled textures across its
 // material, IBL, clustered-light, and SSAO bindings. Ordinary Standard draws
 // use the non-transmission variant and remain valid on the WebGPU minimum of
-// 16; only request the elevated limit when the adapter can provide it.
+// 16. The extended-lighting topology reserves 20, so a device descriptor must
+// request that larger limit when the adapter can provide it; adapter limits are
+// not automatically inherited by requestDevice().
 export const STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES = 17;
 
 export interface DeviceFeatureAdmissionOptions {
@@ -36,18 +39,22 @@ export function deriveDeviceFeatureAdmission(
   if (timestampRequested && adapter.features.has('timestamp-query')) {
     requiredFeatures.push('timestamp-query');
   }
-  const supportsTransmission =
-    (adapter.limits?.maxSampledTexturesPerShaderStage ?? 0) >=
-    STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES;
+  const adapterSampledTextureLimit = adapter.limits?.maxSampledTexturesPerShaderStage ?? 0;
+  const requiredSampledTextureLimit =
+    adapterSampledTextureLimit >= EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES
+      ? EXTENDED_LIGHTING_REQUIRED_SAMPLED_TEXTURES
+      : adapterSampledTextureLimit >= STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES
+        ? STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES
+        : undefined;
   return {
     requiredFeatures,
-    ...(supportsTransmission
-      ? {
+    ...(requiredSampledTextureLimit === undefined
+      ? {}
+      : {
           requiredLimits: {
-            maxSampledTexturesPerShaderStage: STANDARD_PBR_REQUIRED_SAMPLED_TEXTURES,
+            maxSampledTexturesPerShaderStage: requiredSampledTextureLimit,
           },
-        }
-      : {}),
+        }),
   };
 }