@forgeax/engine-render 0.1.20 → 0.1.21

package/src/__tests__/standard-lighting-write.unit.test.ts

@@ -0,0 +1,377 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { RhiError, err as rhiErr, ok as rhiOk } from '@forgeax/engine-rhi';
+import { RhiNullAdapter } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import {
+  createHdrpClusterMembershipBindGroupLayoutDescriptor,
+  getOrCreateHdrpBuffers,
+} from '../hdrp-buffers';
+import { prepareStandardLighting } from '../pipeline/standard-lighting/prepare';
+import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
+import { writeHdrpClusterAndSsaoBuffers } from '../record/frame-lighting';
+import type { RenderFrameState } from '../record/frame-snapshot';
+import type { RenderSystemInternals, RenderSystemRuntime } from '../record/render-context';
+import type { CameraSnapshot } from '../render-contract';
+
+function camera(): CameraSnapshot {
+  return {
+    position: vec3.create(0, 0, 5),
+    world: mat4.create(),
+    fov: Math.PI / 4,
+    aspect: 1,
+    near: 0.1,
+    far: 100,
+    projection: 'perspective',
+    orthoLeft: -1,
+    orthoRight: 1,
+    orthoBottom: -1,
+    orthoTop: 1,
+    tonemap: 'none',
+    exposure: 1,
+    whitePoint: 4,
+    antialias: 'none',
+    bloom: 'off',
+    bloomThreshold: 1,
+    bloomIntensity: 1,
+    bloomBlurRadius: 4,
+    clearColor: [0, 0, 0, 1],
+  };
+}
+
+function internalsWithFirstWriteFailure() {
+  const writes: string[] = [];
+  const payloads = new Map<string, Uint8Array>();
+  const errors: unknown[] = [];
+  const device = {
+    caps: { storageBuffer: true, compute: false, backendKind: 'webgpu' },
+    limits: { maxStorageBufferBindingSize: 1024 * 1024 * 1024 },
+    queue: {
+      writeBuffer(buffer: { readonly label?: string }, _offset: number, data: ArrayBufferView) {
+        const label = buffer.label ?? 'unknown';
+        writes.push(label);
+        payloads.set(label, new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice());
+        return writes.length === 1
+          ? rhiErr(
+              new RhiError({
+                code: 'webgpu-runtime-error',
+                expected: 'upload succeeds',
+                hint: 'test failure',
+              }),
+            )
+          : rhiOk(undefined);
+      },
+      onSubmittedWorkDone: async () => undefined,
+    },
+    createBuffer: (descriptor: { readonly label?: string }) =>
+      rhiOk({ label: descriptor.label } as never),
+    createBindGroupLayout: () => rhiOk({} as never),
+    destroyBuffer: () => rhiOk(undefined),
+  } as unknown as RhiDevice;
+  return {
+    writes,
+    payloads,
+    errors,
+    internals: {
+      device,
+      errorRegistry: { fire: (error: unknown) => errors.push(error) },
+      standardProfile: undefined,
+    },
+  };
+}
+
+describe('Standard Cluster upload ownership', () => {
+  it('returns device-operation-failed instead of publishing after a required upload fails', () => {
+    const source = {
+      kind: 'point' as const,
+      position: vec3.create(0, 0, -4),
+      color: vec3.create(1, 1, 1),
+      intensity: 1,
+      invRangeSquared: 0.25,
+      shadowAtlasLayer: -1,
+    };
+    const prepared = prepareStandardLighting({
+      directional: undefined,
+      local: [{ kind: 'point', shadowed: false, position: source.position, range: 2, source }],
+      view: mat4.create(),
+      projection: mat4.create(),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 1,
+      renderPath: 'forward',
+    });
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    const transport = selectStandardClusterTransport(
+      { compute: false, storageBuffer: true, membershipPipelineReady: false },
+      prepared.value,
+    );
+    expect(transport.ok).toBe(true);
+    if (!transport.ok) return;
+    const { internals, writes, errors } = internalsWithFirstWriteFailure();
+    const result = writeHdrpClusterAndSsaoBuffers(
+      internals as never,
+      { hdrpClusterMembership: null, installedPipelineConfig: undefined } as never,
+      camera(),
+      prepared.value,
+      transport.value,
+    );
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('device-operation-failed');
+    expect(writes).toHaveLength(1);
+    expect(errors).toEqual([]);
+  });
+
+  it('rejects local lights without storage and performs no upload', () => {
+    const source = {
+      kind: 'point' as const,
+      position: vec3.create(0, 0, -4),
+      color: vec3.create(1, 1, 1),
+      intensity: 1,
+      invRangeSquared: 0.25,
+      shadowAtlasLayer: -1,
+    };
+    const prepared = prepareStandardLighting({
+      directional: undefined,
+      local: [{ kind: 'point', shadowed: false, position: source.position, range: 2, source }],
+      view: mat4.create(),
+      projection: mat4.create(),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 1,
+      renderPath: 'forward',
+    });
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    const transport = selectStandardClusterTransport(
+      { compute: true, storageBuffer: false, membershipPipelineReady: false },
+      prepared.value,
+    );
+    expect(transport.ok).toBe(false);
+    if (transport.ok) return;
+    expect(transport.error.code).toBe('standard-cluster-transport-unavailable');
+  });
+
+  it('grows the persistent bundle atomically and retires the old buffers after the fence', async () => {
+    const adapter = new RhiNullAdapter();
+    const deviceResult = await adapter.requestDevice();
+    expect(deviceResult.ok).toBe(true);
+    if (!deviceResult.ok) return;
+    const baseDevice = deviceResult.value;
+    let releaseFence!: () => void;
+    const fence = new Promise<undefined>((resolve) => {
+      releaseFence = () => resolve(undefined);
+    });
+    const device = {
+      caps: baseDevice.caps,
+      features: baseDevice.features,
+      limits: baseDevice.limits,
+      lost: baseDevice.lost,
+      queue: {
+        writeBuffer: baseDevice.queue.writeBuffer.bind(baseDevice.queue),
+        onSubmittedWorkDone: () => fence,
+      },
+      createBuffer: baseDevice.createBuffer.bind(baseDevice),
+      createBindGroupLayout: baseDevice.createBindGroupLayout.bind(baseDevice),
+      destroyBuffer: baseDevice.destroyBuffer.bind(baseDevice),
+    } as unknown as RhiDevice;
+    const errors: unknown[] = [];
+    const runtime = {
+      device,
+      errorRegistry: { fire: (error: unknown) => errors.push(error) },
+    } as unknown as RenderSystemRuntime;
+
+    const small = getOrCreateHdrpBuffers(runtime, { x: 2, y: 2, z: 2 });
+    expect(small).not.toBeNull();
+    if (small === null) return;
+    expect(getOrCreateHdrpBuffers(runtime, { x: 1, y: 1, z: 1 })).toBe(small);
+
+    const grown = getOrCreateHdrpBuffers(runtime, { x: 4, y: 4, z: 4 });
+    expect(grown).not.toBeNull();
+    if (grown === null) return;
+    expect(grown).not.toBe(small);
+    expect(grown.clusterGridBytes).toBeGreaterThan(small.clusterGridBytes);
+
+    await Promise.resolve();
+    const ledger = baseDevice as unknown as {
+      readonly bookkeeper: { isDestroyed(handle: unknown): boolean };
+    };
+    expect(ledger.bookkeeper.isDestroyed(small.lightDataBuffer)).toBe(false);
+    expect(ledger.bookkeeper.isDestroyed(small.clusterGridBuffer)).toBe(false);
+    releaseFence();
+    await Promise.resolve();
+    expect(ledger.bookkeeper.isDestroyed(small.lightDataBuffer)).toBe(true);
+    expect(ledger.bookkeeper.isDestroyed(small.clusterGridBuffer)).toBe(true);
+    expect(ledger.bookkeeper.isDestroyed(grown.lightDataBuffer)).toBe(false);
+    expect(errors).toEqual([]);
+  });
+
+  it('retires a cached bundle when the runtime switches devices', async () => {
+    const adapter = new RhiNullAdapter();
+    const first = await adapter.requestDevice();
+    const second = await adapter.requestDevice();
+    expect(first.ok && second.ok).toBe(true);
+    if (!first.ok || !second.ok) return;
+    const errors: unknown[] = [];
+    const runtime = {
+      device: first.value,
+      errorRegistry: { fire: (error: unknown) => errors.push(error) },
+    } as unknown as RenderSystemRuntime & { device: RhiDevice };
+    const old = getOrCreateHdrpBuffers(runtime, { x: 2, y: 2, z: 2 });
+    expect(old).not.toBeNull();
+    if (old === null) return;
+    runtime.device = second.value;
+    const next = getOrCreateHdrpBuffers(runtime, { x: 2, y: 2, z: 2 });
+    expect(next).not.toBeNull();
+    const ledger = first.value as unknown as {
+      readonly bookkeeper: { isDestroyed(handle: unknown): boolean };
+    };
+    await Promise.resolve();
+    expect(ledger.bookkeeper.isDestroyed(old.lightDataBuffer)).toBe(true);
+    expect(errors).toEqual([]);
+  });
+
+  it('rebuilds the membership bind group when a same-device grid grows', () => {
+    const adapter = new RhiNullAdapter();
+    return adapter.requestDevice().then((deviceResult) => {
+      expect(deviceResult.ok).toBe(true);
+      if (!deviceResult.ok) return;
+      const device = deviceResult.value;
+      const errors: unknown[] = [];
+      const runtime = {
+        device,
+        errorRegistry: { fire: (error: unknown) => errors.push(error) },
+      } as unknown as RenderSystemRuntime;
+      const layout = device
+        .createBindGroupLayout(createHdrpClusterMembershipBindGroupLayoutDescriptor())
+        .unwrap();
+      const emptyFrame = (grid: { x: number; y: number; z: number }) => {
+        const result = prepareStandardLighting({
+          directional: undefined,
+          local: [],
+          view: mat4.create(),
+          projection: mat4.create(),
+          near: 0.1,
+          far: 100,
+          grid,
+          lightCount: 1,
+          renderPath: 'forward',
+        });
+        expect(result.ok).toBe(true);
+        if (!result.ok) throw result.error;
+        return result.value;
+      };
+      const small = emptyFrame({ x: 2, y: 2, z: 2 });
+      const large = emptyFrame({ x: 4, y: 4, z: 4 });
+      const smallTransport = selectStandardClusterTransport(
+        { compute: true, storageBuffer: true, membershipPipelineReady: true },
+        small,
+      );
+      const largeTransport = selectStandardClusterTransport(
+        { compute: true, storageBuffer: true, membershipPipelineReady: true },
+        large,
+      );
+      expect(smallTransport.ok && largeTransport.ok).toBe(true);
+      if (!smallTransport.ok || !largeTransport.ok) return;
+      const frameState = {
+        hdrpClusterMembership: null,
+        installedPipelineConfig: undefined,
+      } as unknown as RenderFrameState;
+      const internals = {
+        device,
+        errorRegistry: runtime.errorRegistry,
+      } as unknown as RenderSystemInternals;
+      const first = writeHdrpClusterAndSsaoBuffers(
+        internals,
+        frameState,
+        camera(),
+        small,
+        smallTransport.value,
+        undefined,
+        true,
+        layout,
+      );
+      expect(first.ok).toBe(true);
+      const firstMembership = frameState.hdrpClusterMembership;
+      expect(firstMembership).not.toBeNull();
+      if (firstMembership === null) return;
+      const firstGridBuffer = firstMembership.clusterGridBuffer;
+      const second = writeHdrpClusterAndSsaoBuffers(
+        internals,
+        frameState,
+        camera(),
+        large,
+        largeTransport.value,
+        undefined,
+        true,
+        layout,
+      );
+      expect(second.ok).toBe(true);
+      expect(frameState.hdrpClusterMembership).not.toBeNull();
+      expect(frameState.hdrpClusterMembership?.bindGroup).not.toBe(firstMembership.bindGroup);
+      expect(frameState.hdrpClusterMembership?.clusterGridBuffer).not.toBe(firstGridBuffer);
+      expect(errors).toEqual([]);
+    });
+  });
+
+  it('keeps the cached LKG and cleans partial candidate buffers after growth allocation fails', async () => {
+    const adapter = new RhiNullAdapter();
+    const baseResult = await adapter.requestDevice();
+    expect(baseResult.ok).toBe(true);
+    if (!baseResult.ok) return;
+    const base = baseResult.value;
+    let createCalls = 0;
+    let failOnCall = Number.POSITIVE_INFINITY;
+    const candidateBuffers: unknown[] = [];
+    const errors: unknown[] = [];
+    const device = {
+      caps: base.caps,
+      features: base.features,
+      limits: base.limits,
+      queue: base.queue,
+      lost: base.lost,
+      createBuffer: (descriptor: Parameters<typeof base.createBuffer>[0]) => {
+        createCalls += 1;
+        if (createCalls === failOnCall) {
+          return rhiErr(
+            new RhiError({
+              code: 'webgpu-runtime-error',
+              expected: 'candidate buffer allocation succeeds',
+              hint: 'test candidate allocation failure',
+            }),
+          );
+        }
+        const created = base.createBuffer(descriptor);
+        if (created.ok) candidateBuffers.push(created.value);
+        return created;
+      },
+      createBindGroupLayout: (descriptor: Parameters<typeof base.createBindGroupLayout>[0]) =>
+        base.createBindGroupLayout(descriptor),
+      destroyBuffer: (buffer: Parameters<typeof base.destroyBuffer>[0]) =>
+        base.destroyBuffer(buffer),
+    } as unknown as RhiDevice;
+    const runtime = {
+      device,
+      errorRegistry: { fire: (error: unknown) => errors.push(error) },
+    } as unknown as RenderSystemRuntime;
+    const small = getOrCreateHdrpBuffers(runtime, { x: 2, y: 2, z: 2 });
+    expect(small).not.toBeNull();
+    if (small === null) return;
+    const oldCandidateCount = candidateBuffers.length;
+    failOnCall = createCalls + 3;
+    const failed = getOrCreateHdrpBuffers(runtime, { x: 8, y: 8, z: 8 });
+    expect(failed).toBeNull();
+    expect(candidateBuffers.length).toBe(oldCandidateCount + 2);
+    const ledger = base as unknown as {
+      readonly bookkeeper: { isDestroyed(handle: unknown): boolean };
+    };
+    expect(ledger.bookkeeper.isDestroyed(candidateBuffers[oldCandidateCount])).toBe(true);
+    expect(ledger.bookkeeper.isDestroyed(candidateBuffers[oldCandidateCount + 1])).toBe(true);
+    expect(ledger.bookkeeper.isDestroyed(small.lightDataBuffer)).toBe(false);
+    expect(getOrCreateHdrpBuffers(runtime, { x: 2, y: 2, z: 2 })).toBe(small);
+    expect(errors).toHaveLength(1);
+  });
+});

package/src/__tests__/standard-lighting.integration.test.ts

@@ -0,0 +1,67 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import {
+  prepareStandardLighting,
+  type StandardLightFrame,
+} from '../pipeline/standard-lighting/prepare';
+
+function makeFrame(lightCount: 1 | 32 | 256, localCount: number): StandardLightFrame {
+  const local = Array.from({ length: localCount }, (_, index) => ({
+    kind: index % 2 === 0 ? ('point' as const) : ('spot' as const),
+    shadowed: false,
+    position: vec3.create((index % 4) - 1.5, 0, -4 - (index % 8)),
+    range: 2,
+  }));
+  return {
+    directional: {
+      kind: 'directional',
+      direction: vec3.create(0, -1, 0),
+      color: vec3.create(1, 1, 1),
+      intensity: 2,
+    },
+    local,
+    view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+    projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount,
+    renderPath: 'forward',
+  };
+}
+
+describe('Standard shared lighting derivation', () => {
+  it.each([
+    [1, 1],
+    [32, 32],
+    [256, 256],
+  ] as const)('accepts the %i local-light budget without truncation', (lightCount, localCount) => {
+    const result = prepareStandardLighting(makeFrame(lightCount, localCount));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.local.length).toBe(localCount);
+    expect(result.value.membershipLightCount).toBe(localCount);
+  });
+
+  it('keeps DirectionalLight global and out of cluster membership', () => {
+    const result = prepareStandardLighting(makeFrame(1, 1));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.directional?.kind).toBe('directional');
+    expect(result.value.membershipLightCount).toBe(1);
+    expect(
+      Array.from(result.value.lightIndexList.slice(0, result.value.membershipEntryCount)),
+    ).not.toContain(1);
+  });
+
+  it('rejects local lights above the 256-light budget without truncation', () => {
+    const result = prepareStandardLighting(makeFrame(256, 257));
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    if (result.error.code !== 'standard-light-budget-exceeded') return;
+    expect(result.error.detail).toEqual({ actual: 257, budget: 256 });
+  });
+});

package/src/__tests__/standard-pipeline.dawn.test.ts

@@ -1,17 +1,29 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
 import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
 import type { RhiDevice } from '@forgeax/engine-rhi';
-import { rhi } from '@forgeax/engine-rhi-webgpu';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
 import { ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { createRenderSurfaceError } from '../errors/render';
-import { standardPipeline } from '../pipeline/standard-pipeline';
+import { GPU_SHADER_STAGE_COMPUTE } from '../gpu-stage';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
+import { prepareStandardLighting } from '../pipeline/standard-lighting/prepare';
+import { deriveStandardTopologyInput } from '../pipeline/standard-lighting/topology';
+import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
+import { STANDARD_CLUSTER_MEMBERSHIP_WGSL, standardPipeline } from '../pipeline/standard-pipeline';
 import { DEFAULT_STANDARD_PROFILE, STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
 import type { RenderPipelineFrame, RenderPipelineTopology } from '../render-pipeline';
 
 function topology(): RenderPipelineTopology {
   return {
     pipelineId: STANDARD_PIPELINE_ID,
-    standardProfile: { ...DEFAULT_STANDARD_PROFILE, lighting: 'clustered', lightCount: 256 },
+    standardProfile: { ...DEFAULT_STANDARD_PROFILE, renderPath: 'deferred', lightCount: 256 },
     config: { ssao: { enabled: true } },
     surface: {
       width: 1,
@@ -21,8 +33,8 @@ function topology(): RenderPipelineTopology {
     },
     camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom: 'on' },
     shadow: {
-      mapSize: 64,
-      cascadeCount: 1,
+      directional: { mapSize: 64, cascadeCount: 1 },
+      spotMapSize: 64,
       pointCount: 0,
       pointFaceSize: 64,
       spotCount: 0,
@@ -38,6 +50,33 @@ function topology(): RenderPipelineTopology {
   };
 }
 
+function clusteredStandardLighting() {
+  const prepared = prepareStandardLighting({
+    directional: undefined,
+    local: [{ kind: 'point' as const, shadowed: false, position: vec3.create(0, 0, -4), range: 2 }],
+    view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+    projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount: 256,
+    renderPath: 'deferred',
+  });
+  if (!prepared.ok) throw prepared.error;
+  const transport = selectStandardClusterTransport(
+    { compute: true, storageBuffer: true, membershipPipelineReady: true },
+    prepared.value,
+  );
+  if (!transport.ok) throw transport.error;
+  const lighting = deriveStandardTopologyInput({
+    kind: 'clustered',
+    prepared: prepared.value,
+    transport: transport.value,
+  });
+  if (!lighting.ok) throw lighting.error;
+  return lighting.value;
+}
+
 describe('forgeax::standard graph on a real WebGPU device', () => {
   it('reports float-chain failures without replacing the last-known-good surface', () => {
     const error = createRenderSurfaceError('sampled-read', {
@@ -60,6 +99,7 @@ describe('forgeax::standard graph on a real WebGPU device', () => {
     const built = standardPipeline.build(
       {
         graph,
+        standardLighting: clusteredStandardLighting(),
         projectGpuDriven: () => ok(undefined),
         contributeFeatures: () => ok(undefined),
       },
@@ -73,4 +113,165 @@ describe('forgeax::standard graph on a real WebGPU device', () => {
       expect(compiled.value.inspect().passes.map((pass) => pass.kind)).toContain('compute');
     }
   });
+
+  it('reads back GPU membership and proves equality with the Prepared canonical list', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device: RhiDevice = (await adapter.requestDevice()).unwrap();
+    const frame = {
+      directional: undefined,
+      local: [
+        { kind: 'point' as const, shadowed: false, position: vec3.create(-0.8, 0, -4), range: 2 },
+        { kind: 'spot' as const, shadowed: false, position: vec3.create(0.8, 0, -6), range: 3 },
+      ],
+      view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+      projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+      near: 0.1,
+      far: 100,
+      grid: { x: 4, y: 3, z: 4 },
+      lightCount: 32 as const,
+      renderPath: 'deferred' as const,
+    };
+    const prepared = prepareStandardLighting(frame);
+    expect(prepared.ok).toBe(true);
+    if (!prepared.ok) return;
+    const { layout, clusterGrid, lightBounds, lightIndexList, membershipEntryCount } =
+      prepared.value;
+
+    const module = await createShaderModule(device, {
+      code: STANDARD_CLUSTER_MEMBERSHIP_WGSL,
+      label: 'standard-cluster-membership-readback',
+    });
+    expect(module.ok).toBe(true);
+    if (!module.ok) return;
+    const bindGroupLayout = device.createBindGroupLayout({
+      label: 'standard-cluster-membership-readback-bgl',
+      entries: [
+        { binding: 0, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'read-only-storage' } },
+        { binding: 1, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'storage' } },
+        { binding: 2, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'uniform' } },
+        { binding: 3, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'read-only-storage' } },
+      ],
+    });
+    expect(bindGroupLayout.ok).toBe(true);
+    if (!bindGroupLayout.ok) return;
+    const pipelineLayout = device.createPipelineLayout({
+      label: 'standard-cluster-membership-readback-pl',
+      bindGroupLayouts: [bindGroupLayout.value],
+    });
+    expect(pipelineLayout.ok).toBe(true);
+    if (!pipelineLayout.ok) return;
+    const pipeline = device.createComputePipeline({
+      label: 'standard-cluster-membership-readback',
+      layout: pipelineLayout.value,
+      compute: { module: module.value, entryPoint: 'cs_cluster_membership' },
+    });
+    expect(pipeline.ok).toBe(true);
+    if (!pipeline.ok) return;
+
+    const clusterGridBuffer = device.createBuffer({
+      label: 'standard-cluster-readback-grid',
+      size: layout.clusterGridU32Length * 4,
+      usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
+    });
+    const lightIndexBuffer = device.createBuffer({
+      label: 'standard-cluster-readback-list',
+      size: layout.lightIndexListCapacity * 4,
+      usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC,
+    });
+    const boundsBuffer = device.createBuffer({
+      label: 'standard-cluster-readback-bounds',
+      size: lightBounds.byteLength,
+      usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_DST,
+    });
+    const uniformBuffer = device.createBuffer({
+      label: 'standard-cluster-readback-uniform',
+      size: 32,
+      usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+    });
+    const readbackSize = Math.max(4, membershipEntryCount * 4);
+    const readbackBuffer = device.createBuffer({
+      label: 'standard-cluster-membership-readback-copy',
+      size: readbackSize,
+      usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+    });
+    expect(
+      clusterGridBuffer.ok &&
+        lightIndexBuffer.ok &&
+        boundsBuffer.ok &&
+        uniformBuffer.ok &&
+        readbackBuffer.ok,
+    ).toBe(true);
+    if (
+      !clusterGridBuffer.ok ||
+      !lightIndexBuffer.ok ||
+      !boundsBuffer.ok ||
+      !uniformBuffer.ok ||
+      !readbackBuffer.ok
+    )
+      return;
+
+    const uniformData = new ArrayBuffer(32);
+    new Uint32Array(uniformData, 0, 4).set([
+      layout.grid.x,
+      layout.grid.y,
+      layout.grid.z,
+      frame.local.length,
+    ]);
+    new Float32Array(uniformData, 16, 4).set([
+      frame.near,
+      frame.far,
+      Math.log(frame.far / frame.near),
+      0,
+    ]);
+    expect(device.queue.writeBuffer(clusterGridBuffer.value, 0, clusterGrid)).toMatchObject({
+      ok: true,
+    });
+    expect(device.queue.writeBuffer(boundsBuffer.value, 0, lightBounds)).toMatchObject({
+      ok: true,
+    });
+    expect(device.queue.writeBuffer(uniformBuffer.value, 0, uniformData)).toMatchObject({
+      ok: true,
+    });
+    const bindings = device.createBindGroup({
+      label: 'standard-cluster-membership-readback-bg',
+      layout: bindGroupLayout.value,
+      entries: [
+        { binding: 0, resource: { kind: 'buffer', value: { buffer: clusterGridBuffer.value } } },
+        { binding: 1, resource: { kind: 'buffer', value: { buffer: lightIndexBuffer.value } } },
+        { binding: 2, resource: { kind: 'buffer', value: { buffer: uniformBuffer.value } } },
+        { binding: 3, resource: { kind: 'buffer', value: { buffer: boundsBuffer.value } } },
+      ],
+    });
+    expect(bindings.ok).toBe(true);
+    if (!bindings.ok) return;
+    const encoder = device.createCommandEncoder({ label: 'standard-cluster-membership-readback' });
+    expect(encoder.ok).toBe(true);
+    if (!encoder.ok) return;
+    const pass = encoder.value.beginComputePass();
+    pass.setPipeline(pipeline.value);
+    pass.setBindGroup(0, bindings.value);
+    pass.dispatchWorkgroups(Math.ceil((layout.grid.x * layout.grid.y * layout.grid.z) / 64));
+    pass.end();
+    encoder.value.copyBufferToBuffer(
+      lightIndexBuffer.value,
+      0,
+      readbackBuffer.value,
+      0,
+      readbackSize,
+    );
+    const finished = encoder.value.finish();
+    expect(finished.ok).toBe(true);
+    if (!finished.ok) return;
+    expect(device.queue.submit([finished.value])).toMatchObject({ ok: true });
+    await device.queue.onSubmittedWorkDone();
+    const mapped = await readbackBuffer.value.mapAsync(1);
+    expect(mapped.ok).toBe(true);
+    if (!mapped.ok) return;
+    const range = mapped.value.getMappedRange();
+    expect(range.ok).toBe(true);
+    if (!range.ok) return;
+    const gpuList = new Uint32Array(range.value.slice(0, membershipEntryCount * 4));
+    expect(Array.from(gpuList)).toEqual(Array.from(lightIndexList.slice(0, membershipEntryCount)));
+    mapped.value.unmap();
+  }, 30_000);
 });