@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/ssao-bgl.test.ts

@@ -0,0 +1,354 @@
+// ssao-bgl.test.ts — feat-20260612-hdrp-ssao M7 (round 2),
+// scope-amend-webgl2-ubo (intensity folded into cluster_uniform.near_far_log.w).
+//
+// Covers w28 / w29 / w44:
+//   w28 — HDRP unified BGL gains 2 SSAO entries (binding 7 texture_2d<f32>,
+//         binding 8 sampler). Existing 5 entries (binding 0 + 3..6) remain
+//         unchanged. Total = 7 entries. Intensity is read by the lighting
+//         shader from cluster_uniform.near_far_log.w (binding 6) — the
+//         dedicated @binding(9) UBO was removed to keep the fragment-stage
+//         UBO count under WebGL2's max_uniform_buffers_per_shader_stage=11.
+//   w29 — A 1x1 r8unorm white fallback texture is lazy-allocated on the
+//         RenderSystemRuntime under label 'hdrp-ssao-fallback-white'; it is
+//         created exactly once and reused on subsequent calls. SSAO disabled
+//         path binds the fallback texture at binding 7.
+//   w44 — createHdrpUnifiedBindGroup always emits 7 bind-group entries
+//         (single-PSO invariant, plan-strategy D-B). Enabled path binds the
+//         real ssaoBlurred texture view + ssaoSampler at bindings 7/8;
+//         disabled path swaps binding 7 to the fallback white texture and
+//         the host writes intensity=0 into cluster_uniform.
+//
+// plan-strategy §D-B / §D-C / §D-F :: tests live in this dedicated file so
+// the existing 5-entry assertions in pipeline.unit.test.ts are migrated
+// holistically (one-cut, no v1/v2 dual fixture).
+
+import type {
+  BindGroupLayout,
+  Buffer,
+  RhiCaps,
+  RhiDevice,
+  Texture,
+  TextureView,
+} from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
+import type { HdrpBuffers } from '../../../render/src/hdrp-buffers';
+import {
+  createHdrpClusterMembershipBindGroup,
+  createHdrpClusterMembershipBindGroupLayoutDescriptor,
+  createHdrpUnifiedBindGroup,
+  getOrCreateSsaoFallbackTexture,
+  packClusterUniform,
+} from '../../../render/src/hdrp-buffers';
+import { createHdrpBindGroupLayoutDescriptor } from '../../../render/src/pipeline-spec';
+import type { RenderSystemRuntime } from '../../../render/src/render-system';
+
+const FRAGMENT_VISIBILITY = 0x2;
+const COMPUTE_VISIBILITY = 0x4;
+
+function mockTexture(label: string): Texture {
+  return { label } as unknown as Texture;
+}
+
+function mockTextureView(label: string): TextureView {
+  return { label } as unknown as TextureView;
+}
+
+function mockBuffer(label: string): Buffer {
+  return { label } as unknown as Buffer;
+}
+
+function makeMockRuntime(capsOverride: Partial<RhiCaps> = {}): {
+  runtime: RenderSystemRuntime;
+  createBuffer: ReturnType<typeof vi.fn>;
+  createTexture: ReturnType<typeof vi.fn>;
+  createTextureView: ReturnType<typeof vi.fn>;
+  createSampler: ReturnType<typeof vi.fn>;
+  createBindGroup: ReturnType<typeof vi.fn>;
+  writeBuffer: ReturnType<typeof vi.fn>;
+  writeTexture: ReturnType<typeof vi.fn>;
+} {
+  const createBuffer = vi.fn().mockImplementation((desc: { label?: string }) => ({
+    ok: true,
+    value: mockBuffer(desc.label ?? 'mock-buf'),
+  }));
+  const createTexture = vi.fn().mockImplementation((desc: { label?: string }) => ({
+    ok: true,
+    value: mockTexture(desc.label ?? 'mock-tex'),
+  }));
+  const createTextureView = vi
+    .fn()
+    .mockImplementation((_tex: unknown, desc: { label?: string }) => ({
+      ok: true,
+      value: mockTextureView(desc?.label ?? 'mock-view'),
+    }));
+  const createSampler = vi.fn().mockReturnValue({ ok: true, value: { label: 'mock-sampler' } });
+  const createBindGroup = vi.fn().mockImplementation((desc: { label?: string }) => ({
+    ok: true,
+    value: { label: desc.label ?? 'mock-bg', _entries: desc },
+  }));
+  const writeBuffer = vi.fn().mockReturnValue({ ok: true, value: undefined });
+  const writeTexture = vi.fn().mockReturnValue({ ok: true, value: undefined });
+
+  const device = {
+    caps: {
+      backendKind: 'webgpu' as const,
+      storageBuffer: true,
+      float32Filterable: true,
+      maxColorAttachments: 8,
+      maxStorageBuffersPerShaderStage: 8,
+      ...capsOverride,
+    },
+    createBuffer,
+    createTexture,
+    createTextureView,
+    createSampler,
+    createBindGroup,
+    queue: {
+      writeBuffer,
+      writeTexture,
+    },
+  } as unknown as RhiDevice;
+
+  const errorRegistry = {
+    fire: vi.fn(),
+    listeners: new Set(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  };
+
+  const runtime = { device, errorRegistry } as unknown as RenderSystemRuntime;
+  return {
+    runtime,
+    createBuffer,
+    createTexture,
+    createTextureView,
+    createSampler,
+    createBindGroup,
+    writeBuffer,
+    writeTexture,
+  };
+}
+
+function fakeHdrpBuffers(): HdrpBuffers {
+  return {
+    storageBuffer: true,
+    lightDataBuffer: mockBuffer('hdrp-light-data'),
+    lightDataBytes: 16384,
+    clusterGridBuffer: mockBuffer('hdrp-cluster-grid'),
+    clusterGridBytes: 1024,
+    lightIndexListBuffer: mockBuffer('hdrp-light-index-list'),
+    lightIndexListBytes: 4096,
+    clusterUniformBuffer: mockBuffer('hdrp-cluster-uniform'),
+    clusterUniformBytes: 32,
+    lightBoundsBuffer: mockBuffer('hdrp-light-bounds'),
+    lightBoundsBytes: 6144,
+    grid: { x: 16, y: 9, z: 24 },
+    unifiedBindGroupLayout: {
+      label: 'hdrp-unified-bgl',
+    } as unknown as HdrpBuffers['unifiedBindGroupLayout'],
+  };
+}
+
+describe('HDRP GPU membership producer bind-group contract', () => {
+  it('preserves the 256-light storage count while keeping the 128-light uniform default', () => {
+    const uniformPayload = new Uint32Array(
+      packClusterUniform({ x: 16, y: 9, z: 24 }, 0.1, 50, 0, 256),
+    );
+    const storagePayload = new Uint32Array(
+      packClusterUniform({ x: 16, y: 9, z: 24 }, 0.1, 50, 0, 256, 256),
+    );
+    expect(uniformPayload[3]).toBe(128);
+    expect(storagePayload[3]).toBe(256);
+  });
+
+  it('keeps enabled SSAO intensity in the zero-punctual-light uniform path', () => {
+    const payload = new Float32Array(packClusterUniform({ x: 16, y: 9, z: 24 }, 0.1, 50, 1, 0));
+    expect(payload[3]).toBe(0);
+    expect(payload[7]).toBe(1);
+  });
+
+  it('uses four compute-only bindings with read-write membership output', () => {
+    const desc = createHdrpClusterMembershipBindGroupLayoutDescriptor();
+    expect(desc.entries?.map((entry) => entry.binding)).toEqual([0, 1, 2, 3]);
+    expect(desc.entries?.every((entry) => entry.visibility === COMPUTE_VISIBILITY)).toBe(true);
+    expect(desc.entries?.find((entry) => entry.binding === 0)?.buffer?.type).toBe(
+      'read-only-storage',
+    );
+    expect(desc.entries?.find((entry) => entry.binding === 1)?.buffer?.type).toBe('storage');
+    expect(desc.entries?.find((entry) => entry.binding === 2)?.buffer?.type).toBe('uniform');
+    expect(desc.entries?.find((entry) => entry.binding === 3)?.buffer?.type).toBe(
+      'read-only-storage',
+    );
+  });
+
+  it('binds cluster grid, membership output, uniform, and CPU bounds in that order', () => {
+    const { runtime, createBindGroup } = makeMockRuntime();
+    const hdrp = fakeHdrpBuffers();
+    const layout = { label: 'membership-layout' } as unknown as BindGroupLayout;
+
+    const bindGroup = createHdrpClusterMembershipBindGroup(runtime, hdrp, layout);
+    expect(bindGroup).not.toBeNull();
+    const desc = createBindGroup.mock.calls[0]?.[0] as
+      | { layout?: BindGroupLayout; entries?: Array<{ binding: number; resource: unknown }> }
+      | undefined;
+    expect(desc?.layout).toBe(layout);
+    expect(desc?.entries?.map((entry) => entry.binding)).toEqual([0, 1, 2, 3]);
+    const resources = desc?.entries?.map(
+      (entry) => (entry.resource as { value?: { buffer?: Buffer } }).value?.buffer,
+    );
+    expect(resources).toEqual([
+      hdrp.clusterGridBuffer,
+      hdrp.lightIndexListBuffer,
+      hdrp.clusterUniformBuffer,
+      hdrp.lightBoundsBuffer,
+    ]);
+  });
+});
+
+// ── w28: BGL descriptor 7 entries (5 cluster + 2 ssao) ────────────────────
+
+describe('w28 — HDRP unified BGL SSAO entries (binding 7/8)', () => {
+  it('descriptor entries.length === 7 (5 cluster + 2 ssao)', () => {
+    const desc = createHdrpBindGroupLayoutDescriptor(true);
+    expect(desc.entries?.length).toBe(7);
+  });
+
+  it('binding 7 is texture_2d<f32> with FRAGMENT visibility (ssaoBlurred)', () => {
+    const desc = createHdrpBindGroupLayoutDescriptor(true);
+    const b7 = desc.entries?.find((e) => e.binding === 7);
+    expect(b7).toBeDefined();
+    expect(b7?.visibility).toBe(FRAGMENT_VISIBILITY);
+    expect(b7?.texture?.sampleType).toBe('float');
+    expect(b7?.texture?.viewDimension ?? '2d').toBe('2d');
+  });
+
+  it('binding 8 is sampler with FRAGMENT visibility (ssaoSampler)', () => {
+    const desc = createHdrpBindGroupLayoutDescriptor(true);
+    const b8 = desc.entries?.find((e) => e.binding === 8);
+    expect(b8).toBeDefined();
+    expect(b8?.visibility).toBe(FRAGMENT_VISIBILITY);
+    expect(b8?.sampler).toBeDefined();
+  });
+
+  it('binding 9 is absent (scope-amend-webgl2-ubo: intensity folded into binding 6)', () => {
+    const desc = createHdrpBindGroupLayoutDescriptor(true);
+    const bindings = desc.entries?.map((e) => e.binding) ?? [];
+    expect(bindings).not.toContain(9);
+  });
+
+  it('existing bindings 0/3/4/5/6 remain unchanged', () => {
+    const desc = createHdrpBindGroupLayoutDescriptor(true);
+    const b0 = desc.entries?.find((e) => e.binding === 0);
+    expect(b0?.buffer?.hasDynamicOffset).toBe(true);
+    for (const b of [3, 4, 5, 6]) {
+      const e = desc.entries?.find((x) => x.binding === b);
+      expect(e, `binding ${b} present`).toBeDefined();
+    }
+  });
+
+  it('all bindings exactly { 0, 3, 4, 5, 6, 7, 8 }', () => {
+    const desc = createHdrpBindGroupLayoutDescriptor(true);
+    const bindings = new Set(desc.entries?.map((e) => e.binding));
+    expect(bindings).toEqual(new Set([0, 3, 4, 5, 6, 7, 8]));
+  });
+});
+
+// ── w29: 1x1 white fallback texture lazy alloc + cached ───────────────────
+
+describe('w29 — 1x1 white fallback texture lazy alloc', () => {
+  it('first call creates 1x1 r8unorm fallback texture with hdrp-ssao-fallback-white label', () => {
+    const { runtime, createTexture, writeTexture } = makeMockRuntime();
+    const tex = getOrCreateSsaoFallbackTexture(runtime);
+    expect(tex).not.toBeNull();
+    expect(createTexture).toHaveBeenCalledTimes(1);
+    const desc = createTexture.mock.calls[0]?.[0] as
+      | { label?: string; format?: string; size?: { width: number; height: number } }
+      | undefined;
+    expect(desc?.label).toBe('hdrp-ssao-fallback-white');
+    expect(desc?.format).toBe('r8unorm');
+    expect(desc?.size?.width).toBe(1);
+    expect(desc?.size?.height).toBe(1);
+    // Single byte 0xFF written for "white" (AO = 1.0).
+    expect(writeTexture).toHaveBeenCalledTimes(1);
+    const writeArgs = writeTexture.mock.calls[0];
+    const data = writeArgs?.[1] as Uint8Array | undefined;
+    expect(data).toBeInstanceOf(Uint8Array);
+    expect(data?.[0]).toBe(255);
+  });
+
+  it('second call returns cached instance (createTexture called only once)', () => {
+    const { runtime, createTexture } = makeMockRuntime();
+    const tex1 = getOrCreateSsaoFallbackTexture(runtime);
+    const tex2 = getOrCreateSsaoFallbackTexture(runtime);
+    expect(tex1).toBe(tex2);
+    expect(createTexture).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns null when device.createTexture fails (charter P3 explicit failure)', () => {
+    const { runtime } = makeMockRuntime();
+    // Override createTexture to fail.
+    (runtime.device as unknown as { createTexture: ReturnType<typeof vi.fn> }).createTexture = vi
+      .fn()
+      .mockReturnValue({
+        ok: false,
+        error: { code: 'webgpu-runtime-error', expected: 'createTexture ok', hint: 'boom' },
+      });
+    const tex = getOrCreateSsaoFallbackTexture(runtime);
+    expect(tex).toBeNull();
+  });
+});
+
+// ── w44: createHdrpUnifiedBindGroup 7-entry invariant (enabled vs disabled) ──
+
+describe('w44 — createHdrpUnifiedBindGroup SSAO entries (binding 7/8)', () => {
+  it('enabled path: bind group has 7 entries with real ssaoBlurred view at binding 7', () => {
+    const { runtime, createBindGroup } = makeMockRuntime();
+    const hdrp = fakeHdrpBuffers();
+    const ssaoBlurredView = mockTextureView('ssao-blurred-view');
+    const meshSsbo = mockBuffer('mesh-ssbo');
+
+    const bg = createHdrpUnifiedBindGroup(runtime, hdrp, meshSsbo, {
+      enabled: true,
+      ssaoBlurredView,
+    });
+    expect(bg).not.toBeNull();
+    const desc = createBindGroup.mock.calls[0]?.[0] as
+      | {
+          entries?: Array<{ binding: number; resource: unknown }>;
+        }
+      | undefined;
+    expect(desc?.entries?.length).toBe(7);
+    const b7 = desc?.entries?.find((e) => e.binding === 7);
+    const b7res = b7?.resource as { kind?: string; value?: unknown } | undefined;
+    expect(b7res?.kind).toBe('textureView');
+    expect(b7res?.value).toBe(ssaoBlurredView);
+    const b8 = desc?.entries?.find((e) => e.binding === 8);
+    expect((b8?.resource as { kind?: string } | undefined)?.kind).toBe('sampler');
+    // scope-amend-webgl2-ubo: binding 9 is gone; intensity flows via
+    // cluster_uniform.near_far_log.w on binding 6.
+    const bindings = new Set(desc?.entries?.map((e) => e.binding));
+    expect(bindings).not.toContain(9);
+  });
+
+  it('disabled path: bind group still has 7 entries; binding 7 = fallback white texture', () => {
+    const { runtime, createBindGroup } = makeMockRuntime();
+    const hdrp = fakeHdrpBuffers();
+    const meshSsbo = mockBuffer('mesh-ssbo');
+
+    const bg = createHdrpUnifiedBindGroup(runtime, hdrp, meshSsbo, { enabled: false });
+    expect(bg).not.toBeNull();
+    const desc = createBindGroup.mock.calls[0]?.[0] as
+      | {
+          entries?: Array<{ binding: number; resource: unknown }>;
+        }
+      | undefined;
+    expect(desc?.entries?.length).toBe(7);
+    const bindings = new Set(desc?.entries?.map((e) => e.binding));
+    expect(bindings).toEqual(new Set([0, 3, 4, 5, 6, 7, 8]));
+    // Binding 7 must resolve to a texture-view of the fallback white texture
+    // (single-PSO invariant; plan-strategy §D-B).
+    const b7 = desc?.entries?.find((e) => e.binding === 7);
+    const b7res = b7?.resource as { kind?: string } | undefined;
+    expect(b7res?.kind).toBe('textureView');
+  });
+});

package/src/__tests__/ssao-buffers.test.ts

@@ -0,0 +1,211 @@
+// ssao-buffers.test.ts — M1 / w3: SSAO buffer lazy-alloc test (TDD red phase).
+//
+// Asserts:
+//  - getOrCreateSsaoBuffers first call creates kernel UBO + noise texture
+//    + SSAO uniform UBO (at least 3 createBuffer/createTexture calls).
+//  - Second call returns same cached instance (0 new device calls).
+//  - Labels match /^hdrp-ssao-/.
+//  - storageBuffer=false still allocates the uniform-backed kernel.
+//
+// AC-05 anchor: lazy alloc + hdrp-ssao-* labels + call-count assertions.
+
+import type { Buffer, RhiCaps, RhiDevice, Texture } from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
+import type { RenderSystemRuntime } from '../../../render/src/render-system';
+import { getOrCreateSsaoBuffers } from '../../../render/src/ssao-buffers';
+
+function mockTexture(label?: string): Texture {
+  return { label: label ?? 'mock-tex' } as unknown as Texture;
+}
+
+function mockBuffer(label?: string): Buffer {
+  return { label: label ?? 'mock-buf' } as unknown as Buffer;
+}
+
+function makeMockRuntime(capsOverride: Partial<RhiCaps> = {}): {
+  runtime: RenderSystemRuntime;
+  createBuffer: ReturnType<typeof vi.fn>;
+  createTexture: ReturnType<typeof vi.fn>;
+  createSampler: ReturnType<typeof vi.fn>;
+} {
+  const createBuffer = vi.fn().mockReturnValue({ ok: true, value: mockBuffer() });
+  const createTexture = vi.fn().mockReturnValue({ ok: true, value: mockTexture() });
+  const createSampler = vi.fn().mockReturnValue({ ok: true, value: { label: 'mock-sampler' } });
+
+  const device = {
+    caps: {
+      backendKind: 'webgpu' as const,
+      storageBuffer: true,
+      float32Filterable: true,
+      maxColorAttachments: 8,
+      maxStorageBuffersPerShaderStage: 4,
+      ...capsOverride,
+    },
+    createBuffer,
+    createTexture,
+    createSampler,
+    queue: {
+      writeBuffer: vi.fn().mockReturnValue({ ok: true, value: undefined }),
+      writeTexture: vi.fn().mockReturnValue({ ok: true, value: undefined }),
+    },
+  } as unknown as RhiDevice;
+
+  const errorRegistry = {
+    fire: vi.fn(),
+    listeners: new Set(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+  };
+
+  const runtime = {
+    device,
+    errorRegistry,
+  } as unknown as RenderSystemRuntime;
+
+  return { runtime, createBuffer, createTexture, createSampler };
+}
+
+describe('getOrCreateSsaoBuffers', () => {
+  it('first call creates kernel UBO + noise texture + uniform UBO (>=3 GPU resources)', () => {
+    const { runtime, createBuffer, createTexture } = makeMockRuntime();
+
+    // The first call creates two UBOs (kernel + per-frame uniform)
+    // + createTexture (noise), plus potentially a staging buffer
+    const bufs = getOrCreateSsaoBuffers(runtime);
+
+    expect(bufs).not.toBeNull();
+    expect(bufs?.kernelBuffer).toBeDefined();
+    expect(bufs?.kernelBytes).toBeGreaterThan(0);
+    expect(bufs?.noiseTexture).toBeDefined();
+    expect(bufs?.uniformBuffer).toBeDefined();
+    expect(bufs?.uniformBytes).toBeGreaterThan(0);
+
+    // At least 3 GPU resource creations: kernel UBO, noise tex, uniform UBO.
+    // Note: noise texture upload may require a staging buffer (extra createBuffer).
+    const totalCalls = createBuffer.mock.calls.length + createTexture.mock.calls.length;
+    expect(totalCalls).toBeGreaterThanOrEqual(3);
+  });
+
+  it('second call returns cached instance (0 new device calls)', () => {
+    const { runtime, createBuffer, createTexture } = makeMockRuntime();
+
+    const a = getOrCreateSsaoBuffers(runtime);
+    expect(a).not.toBeNull();
+
+    // Reset call counts AFTER first call
+    const bufCallsAfterFirst = createBuffer.mock.calls.length;
+    const texCallsAfterFirst = createTexture.mock.calls.length;
+
+    const b = getOrCreateSsaoBuffers(runtime);
+
+    // Same instance identity
+    expect(b).toBe(a);
+
+    // No additional device calls
+    expect(createBuffer.mock.calls.length).toBe(bufCallsAfterFirst);
+    expect(createTexture.mock.calls.length).toBe(texCallsAfterFirst);
+  });
+
+  it('kernel buffer label matches hdrp-ssao-kernel', () => {
+    const { runtime, createBuffer } = makeMockRuntime();
+
+    const calls: Array<Record<string, unknown>> = [];
+    createBuffer.mockImplementation((desc: Record<string, unknown>) => {
+      calls.push(desc);
+      return { ok: true, value: mockBuffer() };
+    });
+
+    getOrCreateSsaoBuffers(runtime);
+
+    const hasKernel = calls.some((c) => c.label === 'hdrp-ssao-kernel');
+    expect(hasKernel).toBe(true);
+  });
+
+  it('SSAO uniform buffer label matches hdrp-ssao-uniform', () => {
+    const { runtime, createBuffer } = makeMockRuntime();
+
+    const calls: Array<Record<string, unknown>> = [];
+    createBuffer.mockImplementation((desc: Record<string, unknown>) => {
+      calls.push(desc);
+      return { ok: true, value: mockBuffer() };
+    });
+
+    getOrCreateSsaoBuffers(runtime);
+
+    const hasUniform = calls.some((c) => c.label === 'hdrp-ssao-uniform');
+    expect(hasUniform).toBe(true);
+  });
+
+  it('noise texture label matches hdrp-ssao-noise', () => {
+    const { runtime, createTexture } = makeMockRuntime();
+
+    const calls: Array<Record<string, unknown>> = [];
+    createTexture.mockImplementation((desc: Record<string, unknown>) => {
+      calls.push(desc);
+      return { ok: true, value: mockTexture() };
+    });
+
+    getOrCreateSsaoBuffers(runtime);
+
+    const hasNoise = calls.some((c) => c.label === 'hdrp-ssao-noise');
+    expect(hasNoise).toBe(true);
+  });
+
+  it('kernel buffer is 1024 bytes (64 vec3 as float32 x3 x4pad)', () => {
+    const { runtime, createBuffer } = makeMockRuntime();
+
+    const calls: Array<Record<string, unknown>> = [];
+    createBuffer.mockImplementation((desc: Record<string, unknown>) => {
+      calls.push(desc);
+      return { ok: true, value: mockBuffer() };
+    });
+
+    getOrCreateSsaoBuffers(runtime);
+
+    const kernelCall = calls.find((c) => c.label === 'hdrp-ssao-kernel');
+    expect(kernelCall).toBeDefined();
+    // 64 * 4 * 4 = 1024 bytes (4 floats per vec3 wgsl padded vec3 alignment)
+    expect(kernelCall?.size).toBe(1024);
+  });
+
+  it('uniform buffer is 192 bytes (3 mat4)', () => {
+    const { runtime, createBuffer } = makeMockRuntime();
+
+    const calls: Array<Record<string, unknown>> = [];
+    createBuffer.mockImplementation((desc: Record<string, unknown>) => {
+      calls.push(desc);
+      return { ok: true, value: mockBuffer() };
+    });
+
+    getOrCreateSsaoBuffers(runtime);
+
+    const uniformCall = calls.find((c) => c.label === 'hdrp-ssao-uniform');
+    expect(uniformCall).toBeDefined();
+    // M7 round-2 D-C: 3 mat4 (192 B) + vec4 intensityPad padded to 256 B
+    // for WebGPU UBO min binding offset alignment.
+    expect(uniformCall?.size).toBe(256);
+  });
+
+  it('storageBuffer=false still allocates the uniform-backed kernel', () => {
+    const { runtime, createBuffer, createTexture } = makeMockRuntime({
+      storageBuffer: false,
+    });
+
+    const bufs = getOrCreateSsaoBuffers(runtime);
+
+    expect(bufs).not.toBeNull();
+    expect(createBuffer.mock.calls.length).toBe(2);
+    expect(createTexture.mock.calls.length).toBe(1);
+    expect(runtime.errorRegistry.fire).not.toHaveBeenCalled();
+  });
+
+  it('storageBuffer=false subsequent calls reuse the same uniform-backed resources', () => {
+    const { runtime } = makeMockRuntime({ storageBuffer: false });
+
+    const first = getOrCreateSsaoBuffers(runtime);
+    expect(getOrCreateSsaoBuffers(runtime)).toBe(first);
+    expect(getOrCreateSsaoBuffers(runtime)).toBe(first);
+
+    expect(runtime.errorRegistry.fire).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/ssao-data.test.ts

@@ -0,0 +1,121 @@
+// ssao-kernel.test.ts -- M1 / w1: kernel distribution test (TDD red phase).
+//
+// Asserts:
+//  - generateSsaoKernel() returns 64 vec3 samples.
+//  - All z >= 0 (tangent-space hemisphere).
+//  - Quadratic falloff: first sample magnitude < last sample magnitude.
+//  - Same seed produces byte-identical output (deterministic).
+//  - generateSsaoNoise() returns 4x4=16 vec3 rotation vectors.
+//  - All noise z == 0 (tangent-plane rotation).
+//
+// AC-03 anchor: kernel length 64 + distribution properties.
+
+import { describe, expect, it } from 'vitest';
+import { generateSsaoKernel, generateSsaoNoise } from '../../../render/src/ssao-buffers';
+
+function readFloat(v: Float32Array, idx: number): number {
+  const val = v[idx];
+  if (val === undefined) throw new Error(`missing float at index ${idx}`);
+  return val;
+}
+
+function readSample(kernel: readonly Float32Array[], i: number): Float32Array {
+  const s = kernel[i];
+  if (s === undefined) throw new Error(`missing sample at index ${i}`);
+  return s;
+}
+
+describe('generateSsaoKernel', () => {
+  it('returns 64 vec3 samples', () => {
+    const kernel = generateSsaoKernel();
+    expect(kernel).toHaveLength(64);
+    for (const v of kernel) {
+      expect(v).toHaveLength(3);
+    }
+  });
+
+  it('all samples have z >= 0 (tangent-space hemisphere)', () => {
+    const kernel = generateSsaoKernel();
+    for (const v of kernel) {
+      expect(readFloat(v, 2)).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it('quadratic falloff: first sample magnitude < last sample magnitude', () => {
+    const kernel = generateSsaoKernel();
+    const s0 = readSample(kernel, 0);
+    const s63 = readSample(kernel, 63);
+    const firstMag = Math.sqrt(
+      readFloat(s0, 0) ** 2 + readFloat(s0, 1) ** 2 + readFloat(s0, 2) ** 2,
+    );
+    const lastMag = Math.sqrt(
+      readFloat(s63, 0) ** 2 + readFloat(s63, 1) ** 2 + readFloat(s63, 2) ** 2,
+    );
+    expect(firstMag).toBeLessThan(lastMag);
+  });
+
+  it('same seed produces byte-identical output', () => {
+    const a = generateSsaoKernel(42);
+    const b = generateSsaoKernel(42);
+    expect(a).toEqual(b);
+  });
+
+  it('different seeds produce different output', () => {
+    const a = generateSsaoKernel(1);
+    const b = generateSsaoKernel(2);
+    let diff = false;
+    for (let i = 0; i < 64; i++) {
+      const sa = readSample(a, i);
+      const sb = readSample(b, i);
+      if (
+        readFloat(sa, 0) !== readFloat(sb, 0) ||
+        readFloat(sa, 1) !== readFloat(sb, 1) ||
+        readFloat(sa, 2) !== readFloat(sb, 2)
+      ) {
+        diff = true;
+        break;
+      }
+    }
+    expect(diff).toBe(true);
+  });
+
+  it('samples are normalized directions scaled by length <= 1', () => {
+    const kernel = generateSsaoKernel();
+    for (const v of kernel) {
+      const mag = Math.sqrt(readFloat(v, 0) ** 2 + readFloat(v, 1) ** 2 + readFloat(v, 2) ** 2);
+      expect(mag).toBeGreaterThan(0);
+      expect(mag).toBeLessThanOrEqual(1);
+    }
+  });
+});
+
+describe('generateSsaoNoise', () => {
+  it('returns a Float32Array of 48 floats (4*4*3)', () => {
+    const noise = generateSsaoNoise();
+    expect(noise).toBeInstanceOf(Float32Array);
+    expect(noise).toHaveLength(48);
+  });
+
+  it('all noise z-components are 0 (tangent-plane rotation)', () => {
+    const noise = generateSsaoNoise();
+    for (let i = 0; i < 16; i++) {
+      const z = noise[i * 3 + 2];
+      expect(z).toBe(0);
+    }
+  });
+
+  it('each rotation vector is non-zero in xy plane', () => {
+    const noise = generateSsaoNoise();
+    for (let i = 0; i < 16; i++) {
+      const x = noise[i * 3 + 0];
+      const y = noise[i * 3 + 1];
+      expect(x !== 0 || y !== 0).toBe(true);
+    }
+  });
+
+  it('same seed produces byte-identical output', () => {
+    const a = generateSsaoNoise(7);
+    const b = generateSsaoNoise(7);
+    expect(a).toEqual(b);
+  });
+});