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

package/src/__tests__/shadow-csm-tile-consistency.test.ts

@@ -0,0 +1,425 @@
+// shadow-csm-tile-consistency.test.ts - bug-20260619-csm-multi-cascade-directional-shadow-broken
+// M1 / AC-04 + AC-06 + AC-07: three-way agreement between
+//   (1) the depth-pass tile  -- the per-cascade setViewport the REAL urp
+//       pipeline issues on the dedicated 'render-system-shadow' encoder,
+//   (2) the sampler-side tile -- the WGSL `_atlasTileOrigin(layer, count)`
+//       formula in lighting-directional.wgsl, and
+//   (3) the matrix slot       -- layer index -> lightViewProj_A..D.
+// For every (count, layer) in {1,2,3,4} x [0,count) all three must point at the
+// same tile / slot, otherwise a cascade samples an empty tile (or another
+// cascade's depth) and the shadow silently vanishes.
+//
+// This DOES NOT re-declare the tile formula and test it against itself (the
+// shadow-csm-atlas.test.ts antipattern: a local computeAtlasLayout copy that
+// could agree with a bug verbatim). The depth tile is captured from the actual
+// urp cascade loop driven through createRenderer + renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }); the
+// sampler tile is read from the WGSL source the GPU actually compiles. The
+// canonical mapping is asserted against BOTH real sources, so a drift on either
+// side breaks the test.
+//
+// AC-04 (count 2/3/4) and AC-06 (count 1) are GREEN today -- they are
+// regression guards proving the failure does not come from tile misplacement.
+// AC-07: documented below as a finding (the 9-tap PCF offset is added in
+// atlas-space and can cross a tile boundary for count > 1).
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import type { World as WorldType } from '@forgeax/engine-ecs';
+import type { Renderer as RendererType } from '@forgeax/engine-render';
+import type { Handle } from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const ENGINE = '../createRenderer';
+
+interface CapturedViewport {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+interface CaptureLog {
+  // setViewport calls on the 'render-system-shadow' encoder, in cascade order.
+  shadowViewports: CapturedViewport[];
+  shadowShaderSources: string[];
+}
+
+function makeMockGL2(): unknown {
+  return {
+    __mockTag: 'webgl2',
+    getExtension: () => null,
+    getParameter: () => 1,
+    isContextLost: () => false,
+  };
+}
+
+function makeMockCanvas(): HTMLCanvasElement {
+  const canvas = {
+    width: 800,
+    height: 600,
+    getContext(kind: string): unknown {
+      if (kind === 'webgl2') return makeMockGL2();
+      if (kind === 'webgpu') {
+        return {
+          __mockTag: 'webgpu-canvas-context',
+          configure: () => undefined,
+          unconfigure: () => undefined,
+          getCurrentTexture: () => ({ createView: () => ({}) }),
+        };
+      }
+      return null;
+    },
+    addEventListener: () => undefined,
+    removeEventListener: () => undefined,
+  };
+  return canvas as Partial<HTMLCanvasElement> as HTMLCanvasElement;
+}
+
+function makeRenderPassEncoder(log: CaptureLog, isShadowEncoder: boolean): Record<string, unknown> {
+  return {
+    setPipeline: () => undefined,
+    setVertexBuffer: () => undefined,
+    setIndexBuffer: () => undefined,
+    setBindGroup: () => undefined,
+    setViewport: (x: number, y: number, w: number, h: number) => {
+      if (isShadowEncoder) log.shadowViewports.push({ x, y, w, h });
+    },
+    draw: () => undefined,
+    drawIndexed: () => undefined,
+    setStencilReference: () => undefined,
+    end: () => undefined,
+  };
+}
+
+function makeMockGPUDevice(log: CaptureLog): unknown {
+  const lost = new Promise<unknown>(() => undefined);
+  return {
+    __mockTag: 'gpu-device',
+    lost,
+    features: new Set(),
+    limits: {},
+    queue: {
+      submit: () => undefined,
+      writeBuffer: () => undefined,
+      writeTexture: () => undefined,
+    },
+    createShaderModule: (desc: { code: string; label?: string }) => {
+      if (desc.label === 'shadow_caster') log.shadowShaderSources.push(desc.code);
+      return { getCompilationInfo: async () => ({ messages: [] }) };
+    },
+    createBindGroupLayout: () => ({}),
+    createPipelineLayout: () => ({}),
+    createRenderPipeline: () => ({}),
+    createBindGroup: () => ({}),
+    createBuffer: () => ({
+      getMappedRange: () => new ArrayBuffer(64),
+      unmap: () => undefined,
+    }),
+    createCommandEncoder: () => {
+      return {
+        beginRenderPass: (descriptor?: { label?: string }) =>
+          makeRenderPassEncoder(log, descriptor?.label?.startsWith('shadowCascade') === true),
+        finish: () => ({}),
+      };
+    },
+    createTexture: () => ({ createView: () => ({}) }),
+    createSampler: () => ({}),
+    destroy: () => undefined,
+  };
+}
+
+function makeMockGPU(device: unknown): unknown {
+  return {
+    requestAdapter: async () => ({ requestDevice: async () => device }),
+    getPreferredCanvasFormat: () => 'bgra8unorm',
+  };
+}
+
+const baseNavigator = { userAgent: 'mock-engine-test' } as Partial<Navigator> as Navigator;
+
+function buildManifestDataUrl(): string {
+  const materialShaderStub = (identifier: string, composedWgsl = '/* stub */') => ({
+    identifier,
+    sourcePath: `${identifier}.wgsl`,
+    composedWgsl,
+    paramSchema: '[]',
+    variants: [],
+  });
+  const manifest = {
+    schemaVersion: '1.0.0',
+    entries: [
+      // A game VFX shader may also be vertex-only. Its earlier position in the
+      // flat manifest must not let content-based triage steal the reserved
+      // shadow-caster identity.
+      {
+        hash: 'custom-vfx',
+        wgsl: '/* custom VFX decoy - @location(0) position; @location(5) color */',
+        glsl: '',
+        bindings: '',
+      },
+      { hash: 'pbr00000', wgsl: '/* pbr stub - calls f_schlick( */', glsl: '', bindings: '' },
+      { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
+      {
+        hash: 'tonemap0',
+        wgsl: '/* tonemap stub - struct TonemapParams { exposure: f32 }; */',
+        glsl: '',
+        bindings: '',
+      },
+      // The flat entry remains for the shader registry, while the matching
+      // reserved materialShaders identifier below owns its runtime identity.
+      // Without it the shadow PSO lookup is null, recordShadowPass early-exits,
+      // and no viewport is captured.
+      {
+        hash: 'shadowcaster0',
+        wgsl: '/* shadow caster stub - @location(0) position vertex-only */',
+        glsl: '',
+        bindings: '',
+      },
+    ],
+    materialShaders: [
+      materialShaderStub('forgeax::default-standard-pbr'),
+      materialShaderStub('forgeax::default-unlit'),
+      materialShaderStub(
+        'forgeax::default-shadow-caster',
+        '/* reserved shadow caster - @location(0) position */',
+      ),
+    ],
+  };
+  return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+}
+
+async function importEngine(): Promise<{
+  createRenderer: (
+    canvas: unknown,
+    opts?: unknown,
+    bundler?: unknown,
+  ) => Promise<{
+    subscribe: (listener: (event: unknown) => void) => () => void;
+    draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
+  }>;
+}> {
+  const engine = (await import(ENGINE)) as {
+    createRenderer: (...args: readonly unknown[]) => Promise<unknown>;
+  };
+  return {
+    createRenderer: async (...args: readonly unknown[]) => {
+      const result = (await engine.createRenderer(...args)) as
+        | { readonly ok: true; readonly value: unknown }
+        | { readonly ok: false; readonly error: unknown };
+      if (!result.ok) throw result.error;
+      return result.value as {
+        subscribe: (listener: (event: unknown) => void) => () => void;
+        draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
+      };
+    },
+  };
+}
+
+async function importEcs(): Promise<{ World: new () => unknown }> {
+  return (await import('@forgeax/engine-ecs')) as never;
+}
+
+async function importComponents(): Promise<{
+  Transform: unknown;
+  MeshFilter: unknown;
+  MeshRenderer: unknown;
+  Camera: unknown;
+  DirectionalLight: unknown;
+  HANDLE_CUBE: Handle<'MeshAsset', 'shared'>;
+}> {
+  return {
+    ...(await import('@forgeax/engine-render')),
+    ...(await import('@forgeax/engine-scene')),
+    ...(await import('@forgeax/engine-assets-runtime')),
+  } as never;
+}
+
+function identityTransform(): Record<string, number[]> {
+  return { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] };
+}
+
+async function captureCascadeViewports(cascadeCount: number, mapSize: number): Promise<CaptureLog> {
+  const log: CaptureLog = { shadowViewports: [], shadowShaderSources: [] };
+  const device = makeMockGPUDevice(log);
+  vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
+  const { createRenderer } = await importEngine();
+  const renderer = await createRenderer(
+    makeMockCanvas(),
+    {},
+    { shaderManifestUrl: buildManifestDataUrl() },
+  );
+  const { World } = await importEcs();
+  const C = await importComponents();
+  const world = new (World as new () => { spawn: (...componentDatas: unknown[]) => unknown })();
+  world.spawn(
+    {
+      component: C.Camera,
+      data: {
+        fov: Math.PI / 4,
+        aspect: 16 / 9,
+        near: 0.1,
+        far: 100,
+        projection: 0,
+        left: -1,
+        right: 1,
+        bottom: -1,
+        top: 1,
+      },
+    },
+    { component: C.Transform, data: { ...identityTransform(), pos: [0, 0, 3] } },
+  );
+  world.spawn({
+    component: C.DirectionalLight,
+    data: {
+      direction: [-0.5, -1, -0.3],
+      color: [1, 1, 1],
+      intensity: 1,
+      cascadeCount,
+      mapSize,
+    },
+  });
+  world.spawn(
+    { component: C.MeshFilter, data: { assetHandle: C.HANDLE_CUBE } },
+    { component: C.MeshRenderer, data: {} },
+    { component: C.Transform, data: identityTransform() },
+  );
+  renderer.subscribe(() => undefined);
+  if (!(renderer as unknown as RendererType).attach(world as WorldType).ok) {
+    throw new Error('World attachment failed');
+  }
+  (world as WorldType).update().unwrap();
+  renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+  return log;
+}
+
+// Canonical cascade->tile mapping. Asserted against BOTH real sources below;
+// it is the shared expectation, not the thing under test.
+function canonicalTile(layer: number, count: number): { col: number; row: number } {
+  const tilesPerSide = Math.ceil(Math.sqrt(count));
+  return { col: layer % tilesPerSide, row: Math.floor(layer / tilesPerSide) };
+}
+
+// Read the WGSL the GPU actually compiles and evaluate its _atlasTileGrid
+// column rule (select(2u, 1u, count<=1u)) so the sampler-side mapping is pinned
+// to the real shader source, not a hand-copy.
+const LIGHTING_WGSL = fileURLToPath(
+  new URL('../../../shader/src/lighting-directional.wgsl', import.meta.url),
+);
+
+function wgslAtlasTilesPerSide(count: number): number {
+  const src = readFileSync(LIGHTING_WGSL, 'utf8');
+  // The shader rule lives in _atlasTileGrid: columns = select(2u,1u,count<=1u).
+  // We assert that exact expression is present, then evaluate it here.
+  const m = src.match(/columns\s*:\s*u32\s*=\s*select\(2u,\s*1u,\s*count\s*<=\s*1u\)/);
+  if (m === null) {
+    throw new Error(
+      'lighting-directional.wgsl _atlasTileGrid columns rule changed; update AC-04 test',
+    );
+  }
+  return count <= 1 ? 1 : 2;
+}
+
+function wgslAtlasTile(layer: number, count: number): { col: number; row: number } {
+  const tilesPerSide = wgslAtlasTilesPerSide(count);
+  return { col: layer % tilesPerSide, row: Math.floor(layer / tilesPerSide) };
+}
+
+describe('CSM cascade tile / matrix / viewport three-way agreement (AC-04, AC-06)', () => {
+  beforeEach(() => {
+    vi.stubGlobal('navigator', { ...baseNavigator });
+  });
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  for (const count of [1, 2, 3, 4]) {
+    it(`count=${count}: depth viewport == _atlasTileOrigin == matrix slot for every layer`, async () => {
+      const mapSize = 1024;
+      const log = await captureCascadeViewports(count, mapSize);
+
+      if (count === 1) {
+        expect(log.shadowShaderSources).toEqual([
+          '/* reserved shadow caster - @location(0) position */',
+        ]);
+      }
+
+      // urp issues exactly one shadow pass (one viewport) per cascade.
+      expect(log.shadowViewports).toHaveLength(count);
+
+      for (let layer = 0; layer < count; layer++) {
+        const vp = log.shadowViewports[layer];
+        expect(vp).toBeDefined();
+        if (vp === undefined) continue;
+
+        // (1) real depth-pass tile, derived from the captured viewport origin.
+        expect(vp.w).toBe(mapSize);
+        expect(vp.h).toBe(mapSize);
+        const depthTile = { col: vp.x / mapSize, row: vp.y / mapSize };
+        expect(Number.isInteger(depthTile.col)).toBe(true);
+        expect(Number.isInteger(depthTile.row)).toBe(true);
+
+        // (2) sampler-side tile from the real WGSL formula.
+        const samplerTile = wgslAtlasTile(layer, count);
+
+        // (3) matrix slot: layer index maps 1:1 to lightViewProj_A..D, so the
+        // slot index IS the layer. The depth pass uses cascadeIndex=layer to
+        // pick the same matrix used by the typed shadow cascade at index i.
+        const matrixSlot = layer;
+
+        // Three-way: all point at the same tile, and the matrix slot is the
+        // layer that produced it.
+        expect(depthTile).toEqual(samplerTile);
+        expect(depthTile).toEqual(canonicalTile(layer, count));
+        expect(matrixSlot).toBe(layer);
+      }
+    }, 30_000);
+  }
+
+  it('AC-06: count=1 collapses to tile (0,0), matrix slot 0, viewport (0,0)', async () => {
+    const mapSize = 1024;
+    const log = await captureCascadeViewports(1, mapSize);
+    expect(log.shadowViewports).toHaveLength(1);
+    const vp = log.shadowViewports[0];
+    expect(vp).toEqual({ x: 0, y: 0, w: mapSize, h: mapSize });
+    expect(wgslAtlasTile(0, 1)).toEqual({ col: 0, row: 0 });
+    expect(canonicalTile(0, 1)).toEqual({ col: 0, row: 0 });
+  }, 30_000);
+});
+
+// AC-07 (9-tap PCF offset coordinate-system self-consistency).
+//
+// _sampleShadowForCascade (lighting-directional.wgsl) computes:
+//   tileUv   = (ndc.xy * 0.5 + 0.5)          // tile-local, range [0,1]
+//   uv       = tileUv * inv + tileOrigin     // atlas-space
+//   OOB early-return tests tileUv in [0,1]   // tile-local
+//   9-tap:   offsetUv = clamp(uv + (x,y)*texel, tileLo, tileHi)  // atlas-space
+//
+// The OOB guard and the sampled coordinate are in DIFFERENT spaces. For count=1
+// (inv=1, tileOrigin=0 => uv == tileUv) they coincide, so there was never a
+// cross-tile risk. For count>1 the 9-tap offset is added in atlas space AFTER
+// the tile-local OOB check, so a fragment within one texel of a tile edge would
+// sample +/-1 texel into the neighbouring tile (a different cascade's depth) and
+// leave a 1-texel seam at cascade boundaries. RC-2/D-6 (bug-20260619) fixed this
+// by clamping every tap to this cascade's tile rect [tileOrigin, tileOrigin+inv)
+// (one texel inset). This guard asserts the clamp is present so the fix cannot
+// silently regress; for count=1 the clamp widens to the full atlas (no-op).
+describe('AC-07: PCF offset coordinate-system self-consistency (static source check)', () => {
+  it('count>1 taps are clamped to the cascade tile rect (no cross-tile sampling)', () => {
+    const src = readFileSync(LIGHTING_WGSL, 'utf8');
+    // Guard the structure: OOB tests tileUv, sampling uses uv = tileUv*tileScale +
+    // tileOrigin, and every 9-tap offset is clamped to the tile rect.
+    expect(src).toMatch(/let\s+uv\s*=\s*tileUv\s*\*\s*tileScale\s*\+\s*tileOrigin/);
+    expect(src).toMatch(/tileUv\.x\s*>=\s*0\.0\s*&&\s*tileUv\.x\s*<=\s*1\.0/);
+    expect(src).toMatch(
+      /offsetUv\s*=\s*clamp\(\s*uv\s*\+\s*vec2<f32>\(f32\(x\),\s*f32\(y\)\)\s*\*\s*texel\s*,\s*tileLo\s*,\s*tileHi\s*\)/,
+    );
+    // One-texel inset tile clamp (merged 5.3-production-shadow-demos variant-free
+    // PCF uses a fixed texel inset; the per-iteration radius clip keeps all taps
+    // of kernels {1,3,5} in-tile).
+    expect(src).toMatch(/let\s+tileLo\s*=\s*tileOrigin\s*\+\s*texel/);
+    expect(src).toMatch(/let\s+tileHi\s*=\s*tileOrigin\s*\+\s*tileScale\s*-\s*texel/);
+    // count=1 => columns=1 => tileScale=(1,1), tileOrigin=(0,0) => uv === tileUv, so
+    // the OOB guard space and sample space coincide regardless of the clamp.
+    expect(wgslAtlasTilesPerSide(1)).toBe(1);
+  });
+});

package/src/__tests__/shadow-csm-ubo.dawn.test.ts

@@ -0,0 +1,252 @@
+// shadow-csm-ubo.dawn.test.ts - feat-20260613-csm-cascaded-shadow-maps-unique-shadow-path
+// M4 / w15: View UBO CSM round-trip dawn-node test (RED, test-first).
+//
+// Covers AC-08: host-side 4-cascade View UBO data write → dawn-node GPU read
+// back. Validates lightViewProj[4] + splitPlanes[4] + cascadeCount/cascadeBlend
+// survive the queue.writeBuffer round-trip without corruption.
+//
+// Layout matches shadow-csm-ubo.test.ts — 196 f32 / 784 B std140 after
+// feat-20260625 w25 folded the spot lightViewProj array into the View UBO tail.
+// The directional cascade offsets [0..125] this test exercises are unchanged;
+// the extra tail (floats 132..195) stays zero in this round-trip.
+//
+// Red phase: common.wgsl still has lightSpaceMatrix (not lightViewProj array);
+// record.ts still writes single lightSpaceMatrix. This test writes the NEW
+// layout directly and reads back independently — it will be red until w16/w25
+// land.
+
+import { describe, expect, it } from 'vitest';
+
+// ── Constants (mirrors current View UBO layout) ─────────────────────────────
+
+const VIEW_UBO_FLOAT_COUNT = 196;
+const VIEW_UBO_BYTES = 784;
+
+// f32 indices matching std140 byte offsets.
+const OFF = {
+  LVP0: 28, // lightViewProj[0] — byte 112
+  INV: 44, // inverseViewProj — byte 176
+  LVP1: 60, // lightViewProj[1] — byte 240
+  LVP2: 76, // lightViewProj[2] — byte 304
+  LVP3: 92, // lightViewProj[3] — byte 368
+  SP0: 108, // splitPlanes[0] — byte 432
+  SP1: 112, // splitPlanes[1] — byte 448
+  SP2: 116, // splitPlanes[2] — byte 464
+  SP3: 120, // splitPlanes[3] — byte 480
+  CC: 124, // cascadeCount — byte 496
+  CB: 125, // cascadeBlend — byte 500
+} as const;
+
+const GPUMapMode: { readonly READ: number } = ((): { readonly READ: number } => {
+  try {
+    const o = globalThis as Record<string, unknown>;
+    const gpuMode = o.GPUMapMode;
+    if (
+      gpuMode !== undefined &&
+      typeof gpuMode === 'object' &&
+      gpuMode !== null &&
+      'READ' in gpuMode
+    ) {
+      return gpuMode as { readonly READ: number };
+    }
+  } catch {
+    /* node env */
+  }
+  return { READ: 1 };
+})();
+
+// GPU buffer usage flags.
+// WebGPU BufferUsage flags (from webgpu spec).
+const MAP_READ = 0x0001; // GPUBufferUsage.MAP_READ
+const MAP_WRITE = 0x0002; // GPUBufferUsage.MAP_WRITE
+const COPY_SRC = 0x0004; // GPUBufferUsage.COPY_SRC
+const COPY_DST = 0x0008; // GPUBufferUsage.COPY_DST
+const UNIFORM = 0x0040; // GPUBufferUsage.UNIFORM
+
+// biome-ignore lint/suspicious/noExplicitAny: dawn-node detection guard
+const dawnReady = typeof navigator !== 'undefined' && (navigator as any).gpu !== undefined;
+
+/**
+ * Build a 196-float View UBO payload with known test values.
+ * All 4 lightViewProj matrices are identity; splitPlanes use
+ * monotonic values; cascadeCount=4, cascadeBlend=0.2.
+ */
+function buildTestPayload(cascadeCount: number, cascadeBlend: number): Float32Array {
+  const f32 = new Float32Array(VIEW_UBO_FLOAT_COUNT);
+
+  // worldViewProj[0] = 1 (identity)
+  f32[0] = 1;
+  f32[5] = 1;
+  f32[10] = 1;
+  f32[15] = 1;
+
+  // lightViewProj[0] — distinct test pattern.
+  // Set diagonal in each cascade to distinguishable values.
+  for (let c = 0; c < 4; c++) {
+    const base = [OFF.LVP0, OFF.LVP1, OFF.LVP2, OFF.LVP3][c] ?? 0;
+    f32[base] = (c + 1) * 0.1; // diag entry [0,0]
+    f32[base + 5] = (c + 1) * 0.1; // [1,1]
+    f32[base + 10] = (c + 1) * 0.1; // [2,2]
+    f32[base + 15] = 1; // [3,3]
+  }
+
+  // inverseViewProj — identity.
+  f32[OFF.INV] = 1;
+  f32[OFF.INV + 5] = 1;
+  f32[OFF.INV + 10] = 1;
+  f32[OFF.INV + 15] = 1;
+
+  // splitPlanes — monotonic known values.
+  const splits = [OFF.SP0, OFF.SP1, OFF.SP2, OFF.SP3];
+  for (let i = 0; i < cascadeCount; i++) {
+    const off = splits[i] ?? 0;
+    f32[off] = (i + 1) * 10.0; // 10, 20, 30, 40
+    // Remaining 3 floats per vec4 slot are padding (zero).
+  }
+
+  // cascadeCount / cascadeBlend.
+  f32[OFF.CC] = cascadeCount;
+  f32[OFF.CB] = cascadeBlend;
+
+  return f32;
+}
+
+describe('View UBO CSM round-trip (w15)', () => {
+  it.skipIf(!dawnReady)("'dawn-binding-missing' -- dawn.node binding injection failed", () => {
+    expect(dawnReady).toBe(true);
+  });
+
+  describe('GPU buffer round-trip (cascadeCount=4)', () => {
+    it('writes 4-cascade payload and reads back identical data', async () => {
+      const gpu = (navigator as unknown as Record<string, unknown>).gpu as GPU;
+      const adapter = await gpu.requestAdapter();
+      expect(adapter).toBeTruthy();
+      if (!adapter) throw new Error('no adapter');
+      const device = await adapter.requestDevice();
+      expect(device).toBeTruthy();
+
+      // Create buffer with COPY_DST (for write) + COPY_SRC (for read).
+      const buf = device.createBuffer({
+        label: 'csm-ubo-roundtrip-n4',
+        size: VIEW_UBO_BYTES,
+        usage: COPY_DST | COPY_SRC | UNIFORM,
+        mappedAtCreation: false,
+      });
+
+      const payload = buildTestPayload(4, 0.2);
+      const stagingUpload = device.createBuffer({
+        size: VIEW_UBO_BYTES,
+        usage: MAP_WRITE | COPY_SRC,
+        mappedAtCreation: true,
+      });
+      new Float32Array(stagingUpload.getMappedRange()).set(payload);
+      stagingUpload.unmap();
+
+      // Copy to the uniform-buffer-style target.
+      const encoder = device.createCommandEncoder();
+      encoder.copyBufferToBuffer(stagingUpload, 0, buf, 0, VIEW_UBO_BYTES);
+      device.queue.submit([encoder.finish()]);
+      await device.queue.onSubmittedWorkDone();
+
+      // Read back via staging buffer.
+      const staging = device.createBuffer({
+        size: VIEW_UBO_BYTES,
+        usage: MAP_READ | COPY_DST,
+        mappedAtCreation: false,
+      });
+      const enc2 = device.createCommandEncoder();
+      enc2.copyBufferToBuffer(buf, 0, staging, 0, VIEW_UBO_BYTES);
+      device.queue.submit([enc2.finish()]);
+      await staging.mapAsync(GPUMapMode.READ);
+      const readback = new Float32Array(staging.getMappedRange());
+
+      // Verify cascadeCount / cascadeBlend.
+      expect(readback[OFF.CC]).toBe(4);
+      expect(readback[OFF.CB]).toBeCloseTo(0.2, 5);
+
+      // Verify splitPlanes.
+      expect(readback[OFF.SP0]).toBeCloseTo(10, 5);
+      expect(readback[OFF.SP1]).toBeCloseTo(20, 5);
+      expect(readback[OFF.SP2]).toBeCloseTo(30, 5);
+      expect(readback[OFF.SP3]).toBeCloseTo(40, 5);
+
+      // Verify lightViewProj[0] diagonal element.
+      expect(readback[OFF.LVP0]).toBeCloseTo(0.1, 5);
+      // Verify lightViewProj[3] diagonal element.
+      expect(readback[OFF.LVP3 + 10]).toBeCloseTo(0.4, 5);
+
+      staging.unmap();
+      staging.destroy();
+      stagingUpload.destroy();
+      buf.destroy();
+      device.destroy();
+    });
+  });
+
+  describe('GPU buffer round-trip (cascadeCount=1)', () => {
+    it('writes 1-cascade payload with zero unused slots', async () => {
+      const gpu = (navigator as unknown as Record<string, unknown>).gpu as GPU;
+      const adapter = await gpu.requestAdapter();
+      expect(adapter).toBeTruthy();
+      if (!adapter) throw new Error('no adapter');
+      const device = await adapter.requestDevice();
+      expect(device).toBeTruthy();
+
+      const buf = device.createBuffer({
+        label: 'csm-ubo-roundtrip-n1',
+        size: VIEW_UBO_BYTES,
+        usage: COPY_DST | COPY_SRC | UNIFORM,
+        mappedAtCreation: false,
+      });
+
+      const payload = buildTestPayload(1, 0.0);
+      const stagingUpload = device.createBuffer({
+        size: VIEW_UBO_BYTES,
+        usage: MAP_WRITE | COPY_SRC,
+        mappedAtCreation: true,
+      });
+      new Float32Array(stagingUpload.getMappedRange()).set(payload);
+      stagingUpload.unmap();
+
+      const encoder = device.createCommandEncoder();
+      encoder.copyBufferToBuffer(stagingUpload, 0, buf, 0, VIEW_UBO_BYTES);
+      device.queue.submit([encoder.finish()]);
+      await device.queue.onSubmittedWorkDone();
+
+      const staging = device.createBuffer({
+        size: VIEW_UBO_BYTES,
+        usage: MAP_READ | COPY_DST,
+        mappedAtCreation: false,
+      });
+      const enc2 = device.createCommandEncoder();
+      enc2.copyBufferToBuffer(buf, 0, staging, 0, VIEW_UBO_BYTES);
+      device.queue.submit([enc2.finish()]);
+
+      await staging.mapAsync(GPUMapMode.READ);
+      const readback = new Float32Array(staging.getMappedRange());
+
+      // cascadeCount=1 with cascadeBlend=0.
+      expect(readback[OFF.CC]).toBe(1);
+      expect(readback[OFF.CB]).toBe(0);
+
+      // cascade 0 splitPlanes: only [0] has data.
+      expect(readback[OFF.SP0]).toBeCloseTo(10, 5);
+      // Unused split slots should be zero.
+      expect(readback[OFF.SP1]).toBe(0);
+      expect(readback[OFF.SP2]).toBe(0);
+      expect(readback[OFF.SP3]).toBe(0);
+
+      // cascade 0 lightViewProj is written.
+      expect(readback[OFF.LVP0]).toBeCloseTo(0.1, 5);
+      // Unused matrix slots should be zero (or identity pattern
+      // from the payload — our builder sets identity diag for all).
+      // What matters: cascade 0 is correct.
+
+      staging.unmap();
+      staging.destroy();
+      stagingUpload.destroy();
+      buf.destroy();
+      device.destroy();
+    });
+  });
+});