@forgeax/engine-runtime 0.1.19 → 0.1.21

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

@@ -131,7 +131,7 @@ function makeMockRuntime(capsOverride: Partial<RhiCaps> = {}): {
 
 function fakeHdrpBuffers(): HdrpBuffers {
   return {
-    storageBuffer: true,
+    device: {} as HdrpBuffers['device'],
     lightDataBuffer: mockBuffer('hdrp-light-data'),
     lightDataBytes: 16384,
     clusterGridBuffer: mockBuffer('hdrp-cluster-grid'),
@@ -150,15 +150,9 @@ function fakeHdrpBuffers(): HdrpBuffers {
 }
 
 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('preserves the full 256-light Standard count in the cluster UBO', () => {
+    const payload = new Uint32Array(packClusterUniform({ x: 16, y: 9, z: 24 }, 0.1, 50, 0, 256));
+    expect(payload[3]).toBe(256);
   });
 
   it('keeps enabled SSAO intensity in the zero-punctual-light uniform path', () => {
@@ -209,12 +203,12 @@ describe('HDRP GPU membership producer bind-group contract', () => {
 
 describe('w28 — HDRP unified BGL SSAO entries (binding 7/8)', () => {
   it('descriptor entries.length === 7 (5 cluster + 2 ssao)', () => {
-    const desc = createHdrpBindGroupLayoutDescriptor(true);
+    const desc = createHdrpBindGroupLayoutDescriptor();
     expect(desc.entries?.length).toBe(7);
   });
 
   it('binding 7 is texture_2d<f32> with FRAGMENT visibility (ssaoBlurred)', () => {
-    const desc = createHdrpBindGroupLayoutDescriptor(true);
+    const desc = createHdrpBindGroupLayoutDescriptor();
     const b7 = desc.entries?.find((e) => e.binding === 7);
     expect(b7).toBeDefined();
     expect(b7?.visibility).toBe(FRAGMENT_VISIBILITY);
@@ -223,7 +217,7 @@ describe('w28 — HDRP unified BGL SSAO entries (binding 7/8)', () => {
   });
 
   it('binding 8 is sampler with FRAGMENT visibility (ssaoSampler)', () => {
-    const desc = createHdrpBindGroupLayoutDescriptor(true);
+    const desc = createHdrpBindGroupLayoutDescriptor();
     const b8 = desc.entries?.find((e) => e.binding === 8);
     expect(b8).toBeDefined();
     expect(b8?.visibility).toBe(FRAGMENT_VISIBILITY);
@@ -231,13 +225,13 @@ describe('w28 — HDRP unified BGL SSAO entries (binding 7/8)', () => {
   });
 
   it('binding 9 is absent (scope-amend-webgl2-ubo: intensity folded into binding 6)', () => {
-    const desc = createHdrpBindGroupLayoutDescriptor(true);
+    const desc = createHdrpBindGroupLayoutDescriptor();
     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 desc = createHdrpBindGroupLayoutDescriptor();
     const b0 = desc.entries?.find((e) => e.binding === 0);
     expect(b0?.buffer?.hasDynamicOffset).toBe(true);
     for (const b of [3, 4, 5, 6]) {
@@ -247,7 +241,7 @@ describe('w28 — HDRP unified BGL SSAO entries (binding 7/8)', () => {
   });
 
   it('all bindings exactly { 0, 3, 4, 5, 6, 7, 8 }', () => {
-    const desc = createHdrpBindGroupLayoutDescriptor(true);
+    const desc = createHdrpBindGroupLayoutDescriptor();
     const bindings = new Set(desc.entries?.map((e) => e.binding));
     expect(bindings).toEqual(new Set([0, 3, 4, 5, 6, 7, 8]));
   });

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

@@ -63,7 +63,14 @@ interface SpyCtx {
 }
 
 function makeDispatchSpyCtx(
-  opts: { ssaoCalcPipeline?: unknown; ssaoBlurPipeline?: unknown; ssaoBgl?: unknown } = {},
+  opts: {
+    ssaoCalcPipeline?: unknown;
+    ssaoBlurPipeline?: unknown;
+    ssaoBgl?: unknown;
+    fxaaPipeline?: unknown;
+    fxaaBindGroupLayout?: unknown;
+    fxaaSampler?: unknown;
+  } = {},
 ): SpyCtx {
   const spy: DispatchSpy = {
     beginRenderPassCalls: [],
@@ -138,10 +145,12 @@ function makeDispatchSpyCtx(
     removeEventListener: vi.fn(),
   };
 
+  const fxaaParamsBuffer = { __label: 'fxaa-params' };
   const runtime = {
     device,
     errorRegistry,
     shaderCache: { get: vi.fn() },
+    getPostProcessParamsBuffer: vi.fn(() => fxaaParamsBuffer),
   } as unknown as RenderSystemRuntime;
 
   // Pre-seed ssao-buffers cache so the record closure resolves a stable
@@ -162,6 +171,13 @@ function makeDispatchSpyCtx(
       ssaoFilteringSampler: null,
       ssaoDepthSampler: null,
       ssaoFallbackRawView: null,
+      // FXAA is part of the same Standard post chain. Keep the fixture's
+      // fullscreen resources complete so recordAll exercises the real FXAA
+      // bind-group path instead of returning early at its capability gate.
+      fxaaPipeline: 'fxaaPipeline' in opts ? opts.fxaaPipeline : { __label: 'fxaa-pipeline' },
+      fxaaBindGroupLayout:
+        'fxaaBindGroupLayout' in opts ? opts.fxaaBindGroupLayout : { __label: 'fxaa-bgl' },
+      fxaaSampler: 'fxaaSampler' in opts ? opts.fxaaSampler : { __label: 'fxaa-sampler' },
     },
   };
 
@@ -215,7 +231,6 @@ function makeDispatchSpyCtx(
     meshBindGroup: null,
     frameState: {
       perFrameGraph: mockPerFrameGraph,
-      isHdrpActive: true,
       installedPipelineConfig: { ssao: { enabled: true, intensity: 1.0 } },
       // Post-process bind group identity cache (bloom / fxaa / ssao). Keyed on
       // the graph-resolved views so resize rebuilds automatically.
@@ -673,6 +688,7 @@ function makePostProcessRecordCtx(): {
     draw: vi.fn(),
     end: vi.fn(),
   };
+  const fxaaParamsBuffer = { label: 'fxaa-params' };
   const device = {
     createBindGroup: vi.fn((desc: PostProcessBindGroupCreate) => {
       bindGroupCreates.push(desc);
@@ -711,6 +727,7 @@ function makePostProcessRecordCtx(): {
     runtime: {
       device: { ...device, caps: { storageBuffer: true } },
       errorRegistry: { fire: vi.fn() },
+      getPostProcessParamsBuffer: vi.fn(() => fxaaParamsBuffer),
     },
     store: { getCubemapGpuView: vi.fn() },
     encoder: {

package/src/__tests__/systems.unit.test.ts

@@ -120,6 +120,7 @@ import { INSTANCE_STORAGE_STRIDE_FLOATS } from '../../../render/src/record/mesh-
 import { selectSwapChainFormat } from '../../../render/src/render-system';
 import { createSkinPaletteAllocator } from '../../../render/src/systems/skin-palette-allocator';
 import type { TransparentEntry } from '../../../render/src/systems/transparent-sort-config';
+import { createTemporalFrameTransaction } from '../../../render/src/temporal/frame';
 import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 import { drawWithOwners } from './renderer-test-utils';
 
@@ -447,9 +448,9 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
     ];
   }
 
-  describe('Camera schema (19 fields: 17 f32 + clearColor array + autoAspect bool after w9 + tonemap-mvp + fxaa + bloom + clearColor + aspect-sync extensions)', () => {
-    it('Camera.schema has 19 fields (17 f32 + clearColor array + autoAspect bool: perspective quartet + projection + ortho quartet + tonemap trio + antialias + bloom quartet + clearColor + autoAspect)', () => {
-      expect(Object.keys(Camera.fields).length).toBe(20);
+  describe('Camera schema (21 fields: 17 f32 + clearColor array + autoAspect bool + target after render-target extension)', () => {
+    it('Camera.schema has 21 fields (17 f32 + clearColor array + autoAspect bool + target: perspective quartet + projection + ortho quartet + tonemap trio + antialias + bloom quartet + clearColor + autoAspect)', () => {
+      expect(Object.keys(Camera.fields).length).toBe(21);
       expect(componentFieldType(Camera, 'fov')).toBe('f32');
       expect(componentFieldType(Camera, 'aspect')).toBe('f32');
       expect(componentFieldType(Camera, 'near')).toBe('f32');
@@ -475,6 +476,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       // feat-20260617-host-engine-contract-and-video-cutscene / M3: aspect-sync
       // opt-out flag (bool column tier).
       expect(componentFieldType(Camera, 'autoAspect')).toBe('bool');
+      expect(componentFieldType(Camera, 'target')).toBe('shared<RenderTarget>');
     });
   });
 
@@ -573,6 +575,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
     directionalCount: 0,
     point: [],
     spot: [],
+    directionalShadowError: undefined,
     lightSpaceMatrix: undefined,
     shadowMapSize: undefined,
     pointShadow: [],
@@ -762,8 +765,11 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         [],
         {
           frameNumber: 0,
+          temporalFrameTransaction: createTemporalFrameTransaction({ deviceEpoch: 0 }),
+          temporalFrameInput: undefined,
           compiledFrameGraph: null,
           compiledFrameGraphTopologyKey: null,
+          compiledFrameGraphGeneration: 0,
           retiredCompiledFrameGraphs: new Set(),
           instanceBuffers: new Map(),
           transientInstanceBuffers: [],
@@ -784,8 +790,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
           installedPipelineHandle: 0,
           activePipeline: urpPipeline,
           installedPipelineConfig: undefined,
-          isHdrpActive: false,
-          hdrpOncePerFrameFired: new Set(),
+          standardOncePerFrameFired: new Set(),
         },
         { unlit: 0 },
         { createBindGroup: 0, keys: [] },
@@ -817,8 +822,11 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         [],
         {
           frameNumber: 0,
+          temporalFrameTransaction: createTemporalFrameTransaction({ deviceEpoch: 0 }),
+          temporalFrameInput: undefined,
           compiledFrameGraph: null,
           compiledFrameGraphTopologyKey: null,
+          compiledFrameGraphGeneration: 0,
           retiredCompiledFrameGraphs: new Set(),
           instanceBuffers: new Map(),
           transientInstanceBuffers: [],
@@ -839,8 +847,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
           installedPipelineHandle: 0,
           activePipeline: urpPipeline,
           installedPipelineConfig: undefined,
-          isHdrpActive: false,
-          hdrpOncePerFrameFired: new Set(),
+          standardOncePerFrameFired: new Set(),
         },
         { unlit: 0 },
         { createBindGroup: 0, keys: [] },
@@ -909,8 +916,9 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
   // --- from fxaa-pipeline.test.ts ---
 
   describe('feat-20260528-fxaa-post-processing M2 w8: FXAA pipeline construction (success path)', () => {
-    it('D-2: FXAA BGL has exactly 2 entries: @binding(0) texture_2d<f32> + @binding(1) sampler, no UBO', () => {
-      // plan-strategy D-2 specifies 2-entry BGL with no UBO entry.
+    it('D-2: FXAA BGL has exactly 3 entries: texture + sampler + dither policy UBO', () => {
+      // FXAA owns a per-pass output-policy UBO so pipeline asset config can
+      // disable dither without rebuilding the shader or graph topology.
       // The sampler entry uses { type: 'filtering' } (linear sampling).
       const bglEntries = [
         {
@@ -923,15 +931,21 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
           visibility: 2, // GPU_SHADER_STAGE_FRAGMENT = 0x2
           sampler: { type: 'filtering' },
         },
+        {
+          binding: 2,
+          visibility: 2,
+          buffer: { type: 'uniform' },
+        },
       ];
-      expect(bglEntries).toHaveLength(2);
+      expect(bglEntries).toHaveLength(3);
       expect(bglEntries[0]?.binding).toBe(0);
       expect(bglEntries[0]?.texture).toBeDefined();
       expect(bglEntries[1]?.binding).toBe(1);
       expect(bglEntries[1]?.sampler).toBeDefined();
-      // D-2 explicitly: no UBO entry (no buffer-type binding).
+      expect(bglEntries[2]?.binding).toBe(2);
+      expect(bglEntries[2]?.buffer).toEqual({ type: 'uniform' });
       const hasBuffer = bglEntries.some((e) => 'buffer' in (e as Record<string, unknown>));
-      expect(hasBuffer).toBe(false);
+      expect(hasBuffer).toBe(true);
     });
 
     it('D-3: FXAA pipeline target format = swap-chain storage format (non-srgb, helper Channel 2 truth)', () => {
@@ -1915,10 +1929,10 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
             return 'mesh-ssbo-capacity';
           case 'mesh-ssbo-ceiling-reached':
             return 'mesh-ssbo-ceiling';
-          case 'hdrp-light-budget-exceeded':
-            return 'hdrp-budget';
-          case 'hdrp-index-list-overflow':
-            return 'hdrp-overflow';
+          case 'standard-light-budget-exceeded':
+            return 'standard-budget';
+          case 'standard-cluster-index-overflow':
+            return 'standard-overflow';
         }
       }
       expect(exhaustive('skin-joint-count-exceeded')).toBe('joint-count');
@@ -2081,8 +2095,10 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       );
     });
 
-    it('imports View from forgeax_view::common', () => {
-      expect(source).toEqual(expect.stringContaining('#import forgeax_view::common::{View'));
+    it('imports View from forgeax_view::common as the sole view ABI', () => {
+      expect(source).toEqual(expect.stringContaining('#import forgeax_view::common::View'));
+      expect(source).not.toContain('FogRay');
+      expect(source).not.toContain('fogRayFromNdc');
     });
 
     it('imports fullscreen_triangle from forgeax_view::common', () => {
@@ -3179,6 +3195,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
     directionalCount: 0,
     point: [],
     spot: [],
+    directionalShadowError: undefined,
     lightSpaceMatrix: undefined,
     shadowMapSize: undefined,
     pointShadow: [],
@@ -3361,11 +3378,12 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
   }
 
   function makePipelineState(
-    internals: { _fakes: Record<string, unknown> },
+    internals: { _fakes: Record<string, unknown>; device?: unknown },
     hdrAlreadyAllocated: boolean,
   ): unknown {
     const f = internals._fakes;
     return {
+      device: internals.device,
       meshes: new Map(),
       format: 'bgra8unorm',
       colorAttachmentFormat: 'bgra8unorm-srgb',
@@ -3450,8 +3468,11 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         [],
         {
           frameNumber: 0,
+          temporalFrameTransaction: createTemporalFrameTransaction({ deviceEpoch: 0 }),
+          temporalFrameInput: undefined,
           compiledFrameGraph: null,
           compiledFrameGraphTopologyKey: null,
+          compiledFrameGraphGeneration: 0,
           retiredCompiledFrameGraphs: new Set(),
           instanceBuffers: new Map(),
           transientInstanceBuffers: [],
@@ -3472,8 +3493,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
           installedPipelineHandle: 0,
           activePipeline: urpPipeline,
           installedPipelineConfig: undefined,
-          isHdrpActive: false,
-          hdrpOncePerFrameFired: new Set(),
+          standardOncePerFrameFired: new Set(),
         },
         { unlit: 0 },
         { createBindGroup: 0, keys: [] },
@@ -3569,8 +3589,11 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         [],
         {
           frameNumber: 0,
+          temporalFrameTransaction: createTemporalFrameTransaction({ deviceEpoch: 0 }),
+          temporalFrameInput: undefined,
           compiledFrameGraph: null,
           compiledFrameGraphTopologyKey: null,
+          compiledFrameGraphGeneration: 0,
           retiredCompiledFrameGraphs: new Set(),
           instanceBuffers,
           warnedZeroLightStandard: false,
@@ -3590,8 +3613,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
           installedPipelineHandle: 0,
           activePipeline: urpPipeline,
           installedPipelineConfig: undefined,
-          isHdrpActive: false,
-          hdrpOncePerFrameFired: new Set(),
+          standardOncePerFrameFired: new Set(),
         },
         { unlit: 0 },
         { createBindGroup: 0, keys: [] },
@@ -3642,8 +3664,11 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         [],
         {
           frameNumber: 0,
+          temporalFrameTransaction: createTemporalFrameTransaction({ deviceEpoch: 0 }),
+          temporalFrameInput: undefined,
           compiledFrameGraph: null,
           compiledFrameGraphTopologyKey: null,
+          compiledFrameGraphGeneration: 0,
           retiredCompiledFrameGraphs: new Set(),
           instanceBuffers,
           warnedZeroLightStandard: false,
@@ -3663,8 +3688,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
           installedPipelineHandle: 0,
           activePipeline: urpPipeline,
           installedPipelineConfig: undefined,
-          isHdrpActive: false,
-          hdrpOncePerFrameFired: new Set(),
+          standardOncePerFrameFired: new Set(),
         },
         { unlit: 0 },
         { createBindGroup: 0, keys: [] },
@@ -8323,10 +8347,10 @@ type ExtractFramesWithPipeline = (
 }
 
 // ── feat-20260612-skin-palette-per-frame-upload M3 / m3-1: record-stage ──
-// dynOffset[1] truth-value + skin BG cache miss=1 + hit=N-1 stats counter.
+// dynOffset[1]/[2] truth-value + skin BG cache miss=1 + hit=N-1 stats counter.
 //
 // Why this block exists:
-//   M3 lifts the record-stage `group2DynamicOffsets` second slot from a
+//   M3 lifts the record-stage `group2DynamicOffsets` palette slots from a
 //   hard-coded `0` (PR #353 stub) to the per-entity `entry.source.skin
 //   .byteOffset` cursor that M2 m2-6 wired into the extract output. The
 //   acceptanceCheck calls for the literal text `group2DynamicOffsets[1]
@@ -8338,8 +8362,8 @@ type ExtractFramesWithPipeline = (
 // What the assertions cover:
 //   (a) The test-local offset oracle mirrors the production main-pass
 //       geometry contract. With skinByteOffset !== undefined the returned
-//       tuple's [1] slot equals the supplied byteOffset (the contract:
-//       `group2DynamicOffsets[1] === byteOffset`); with skinByteOffset ===
+//       tuple's [1] and [2] slots equal the supplied byteOffset (the
+//       temporal contract); with skinByteOffset ===
 //       undefined it returns a length-1 tuple (non-skin paths preserved).
 //   (b) N=3 sequential lookups
 //       against the same `(meshStorageBuffer, skinPaletteAllocator
@@ -8366,7 +8390,9 @@ type ExtractFramesWithPipeline = (
         skinByteOffset: number | undefined,
       ): readonly number[] => {
         const meshOffset = meshSlotIdx * MESH_PER_ENTITY_STRIDE;
-        return skinByteOffset === undefined ? [meshOffset] : [meshOffset, skinByteOffset];
+        return skinByteOffset === undefined
+          ? [meshOffset]
+          : [meshOffset, skinByteOffset, skinByteOffset];
       };
 
       // Skin path: second slot must equal the per-entity byteOffset cursor
@@ -8375,12 +8401,12 @@ type ExtractFramesWithPipeline = (
       // (first allocateSlice), cursor=256 (second 1-joint slice), cursor
       // =16320 (the worst-case 255-joint slice end).
       const skinAt0 = computeSkinGroup2DynOffsets(0, 0);
-      expect(skinAt0).toHaveLength(2);
+      expect(skinAt0).toHaveLength(3);
       // group2DynamicOffsets[1] === byteOffset (literal assertion text per acceptanceCheck)
       expect(skinAt0[1]).toBe(0);
 
       const skinAt256 = computeSkinGroup2DynOffsets(1, 256);
-      expect(skinAt256).toHaveLength(2);
+      expect(skinAt256).toHaveLength(3);
       // group2DynamicOffsets[1] === byteOffset
       expect(skinAt256[1]).toBe(256);
       // mesh slot continues to follow the 256-byte stride: meshSlotIdx * 256.
@@ -8388,7 +8414,7 @@ type ExtractFramesWithPipeline = (
 
       const byteOffsetWorst = 254 * 256;
       const skinAtEnd = computeSkinGroup2DynOffsets(2, byteOffsetWorst);
-      expect(skinAtEnd).toHaveLength(2);
+      expect(skinAtEnd).toHaveLength(3);
       // group2DynamicOffsets[1] === byteOffset
       expect(skinAtEnd[1]).toBe(byteOffsetWorst);
       expect(skinAtEnd[0]).toBe(2 * 256);

package/src/__tests__/texture-dimensions.browser.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'vitest';
+
+const TEXTURE_BINDING = 0x04;
+const COPY_DST = 0x08;
+const COPY_SRC = 0x01;
+const STORAGE_BINDING = 0x80;
+const MAP_READ = 0x0001;
+const COMPUTE_STAGE = 1;
+
+type ProbeResult =
+  | { readonly status: 'ready'; readonly samples: readonly (readonly number[])[] }
+  | { readonly status: 'unavailable'; readonly reason: string };
+
+async function probe(): Promise<ProbeResult> {
+  if (!('gpu' in navigator)) return { status: 'unavailable', reason: 'webgpu-unavailable' };
+  const adapter = await navigator.gpu.requestAdapter();
+  if (adapter === null) return { status: 'unavailable', reason: 'adapter-unavailable' };
+  const device = await adapter.requestDevice();
+  const texture = device.createTexture({
+    size: { width: 2, height: 2, depthOrArrayLayers: 2 },
+    dimension: '3d',
+    format: 'rgba8unorm',
+    usage: TEXTURE_BINDING | COPY_DST,
+  });
+  const arrayTexture = device.createTexture({
+    size: { width: 2, height: 2, depthOrArrayLayers: 2 },
+    dimension: '2d',
+    format: 'rgba8unorm',
+    usage: TEXTURE_BINDING | COPY_DST,
+  });
+  const samples = new Uint8Array(256 * 2 * 2);
+  for (let point = 0; point < 8; point += 1) {
+    const z = Math.floor(point / 4);
+    const y = Math.floor((point % 4) / 2);
+    const x = point % 2;
+    const offset = z * 512 + y * 256 + x * 4;
+    samples[offset] = point + 1;
+    samples[offset + 3] = 255;
+  }
+  const layout = { offset: 0, bytesPerRow: 256, rowsPerImage: 2 };
+  const extent = { width: 2, height: 2, depthOrArrayLayers: 2 };
+  device.queue.writeTexture({ texture: arrayTexture }, samples, layout, extent);
+  device.queue.writeTexture({ texture }, samples, layout, extent);
+  const output = device.createBuffer({ size: 256, usage: STORAGE_BINDING | COPY_SRC });
+  const readback = device.createBuffer({ size: 256, usage: MAP_READ | COPY_DST });
+  const module = device.createShaderModule({
+    code: `
+      @group(0) @binding(0) var array_tex: texture_2d_array<f32>;
+      @group(0) @binding(1) var volume_tex: texture_3d<f32>;
+      @group(0) @binding(2) var<storage, read_write> output: array<vec4<u32>>;
+      fn to_byte(value: f32) -> u32 {
+        return u32(round(value * 255.0));
+      }
+      @compute @workgroup_size(1)
+      fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+        let point = id.x;
+        let coord = vec3<i32>(i32(point % 2u), i32((point / 2u) % 2u), i32(point / 4u));
+        let array_value = textureLoad(array_tex, coord.xy, coord.z, 0);
+        let volume_value = textureLoad(volume_tex, coord, 0);
+        output[point] = vec4<u32>(to_byte(array_value.r), 0u, 0u, 0u);
+        output[point + 8u] = vec4<u32>(to_byte(volume_value.r), 0u, 0u, 0u);
+      }
+    `,
+  });
+  const bindGroupLayout = device.createBindGroupLayout({
+    entries: [
+      { binding: 0, visibility: COMPUTE_STAGE, texture: { viewDimension: '2d-array' } },
+      { binding: 1, visibility: COMPUTE_STAGE, texture: { viewDimension: '3d' } },
+      {
+        binding: 2,
+        visibility: COMPUTE_STAGE,
+        buffer: { type: 'storage' },
+      },
+    ],
+  });
+  const pipeline = device.createComputePipeline({
+    layout: device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] }),
+    compute: { module, entryPoint: 'main' },
+  });
+  const bindGroup = device.createBindGroup({
+    layout: bindGroupLayout,
+    entries: [
+      { binding: 0, resource: arrayTexture.createView({ dimension: '2d-array' }) },
+      { binding: 1, resource: texture.createView({ dimension: '3d' }) },
+      { binding: 2, resource: { buffer: output } },
+    ],
+  });
+  const encoder = device.createCommandEncoder();
+  const pass = encoder.beginComputePass();
+  pass.setPipeline(pipeline);
+  pass.setBindGroup(0, bindGroup);
+  pass.dispatchWorkgroups(8);
+  pass.end();
+  encoder.copyBufferToBuffer(output, 0, readback, 0, 256);
+  device.queue.submit([encoder.finish()]);
+  await readback.mapAsync(MAP_READ);
+  const actual = new Uint8Array(readback.getMappedRange()).slice();
+  readback.unmap();
+  const observed = Array.from({ length: 8 }, (_, point) => [
+    actual[point * 16] ?? 0,
+    actual[(point + 8) * 16] ?? 0,
+  ]);
+  const expected = Array.from({ length: 8 }, (_, point) => point + 1);
+  if (
+    observed.some(
+      ([arraySample, volumeSample], point) =>
+        arraySample !== expected[point] || volumeSample !== expected[point],
+    )
+  ) {
+    return { status: 'unavailable', reason: 'gpu-readback-mismatch' };
+  }
+  return { status: 'ready', samples: observed };
+}
+
+describe('browser texture dimensions', () => {
+  it('returns an observable WebGPU status instead of silently accepting a bad view', async () => {
+    const result = await probe();
+    expect(['ready', 'unavailable']).toContain(result.status);
+    if (result.status === 'unavailable') expect(result.reason.length).toBeGreaterThan(0);
+    if (result.status === 'ready') {
+      expect(result.samples).toHaveLength(8);
+      expect(
+        result.samples.map(([arraySample, volumeSample]) => [arraySample, volumeSample]),
+      ).toEqual(Array.from({ length: 8 }, (_, point) => [point + 1, point + 1]));
+    }
+  });
+});

package/src/__tests__/transcode-fallback.unit.test.ts

@@ -126,7 +126,11 @@ function wireFetch(
               {
                 guid: GUID_TEX,
                 kind: 'texture',
-                payload: { width: 4, height: 4, colorSpace },
+                payload: {
+                  shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
+                  colorSpace,
+                  mips: { kind: 'none' },
+                },
                 refs: [],
                 artifacts: {
                   body: {

package/src/__tests__/view-ubo-layout.browser.test.ts

@@ -1,6 +1,7 @@
 // view-ubo-layout.browser.test.ts - feat-20260518-pbr-direct-lighting-mvp
-// feat-20260531-skybox-env-background M2 / w4 (TDD red): VIEW_UBO_BYTES
-// 112 -> 176 -> 240 layout (worldViewProj 64 B + lightDir 16 B + lightColor
+// feat-20260827-directional-csm-pcss-quality M1: VIEW_UBO_BYTES remains 960
+// while the View slot remains 1024 B. The prefix layout is unchanged and the
+// directional shadow carrier reuses the existing tail pad.
 // 16 B + cameraPos 16 B + lightSpaceMatrix 64 B + inverseViewProj 64 B;
 // std140 vec3 padded to 16-byte boundaries).
 //
@@ -44,14 +45,16 @@ const VIEW_UBO_OFFSETS = {
   lightSpaceMatrix: 112,
   inverseViewProj: 176,
 } as const;
-const VIEW_UBO_BYTES = 240;
+const VIEW_UBO_BYTES = 960;
+const DIRECTIONAL_FILTER_OFFSET = 512;
+const SPOT_LIGHT_VIEW_PROJ_OFFSET = 528;
 
 describe('w4 view UBO 240 B std140 layout (AC-06, browser)', () => {
-  it.skipIf(!browserReady)('host write payload is exactly 240 bytes (60 floats)', () => {
-    // The host (render-system-record.ts) builds a Float32Array(60) and
+  it.skipIf(!browserReady)('host write payload is exactly 960 bytes (240 floats)', () => {
+    // The host (view-ubo.ts) builds a Float32Array(240) and
     // emits a single queue.writeBuffer. Asserting the size lock here keeps
     // the host shape and shader ABI in agreement before the GPU sees it.
-    const payload = new Float32Array(60);
+    const payload = new Float32Array(240);
     expect(payload.byteLength).toBe(VIEW_UBO_BYTES);
   });
 
@@ -63,17 +66,17 @@ describe('w4 view UBO 240 B std140 layout (AC-06, browser)', () => {
     expect(VIEW_UBO_OFFSETS.lightSpaceMatrix).toBe(112);
     expect(VIEW_UBO_OFFSETS.inverseViewProj).toBe(176);
     // Buffer total = inverseViewProj offset + mat4 (64 B) = 240.
-    expect(VIEW_UBO_OFFSETS.inverseViewProj + 64).toBe(VIEW_UBO_BYTES);
+    expect(VIEW_UBO_OFFSETS.inverseViewProj + 64).toBe(240);
   });
 
   it.skipIf(!browserReady)(
     'host packs lightDir / lightColor / cameraPos at canonical std140 slots',
     () => {
       // Canonical packing order documented in plan-strategy D-4: the host
-      // builds a 60-float buffer mirroring the shader-side `View` struct
+      // builds a 240-float buffer mirroring the shader-side `View` struct
       // field order. AC-06: existing field offsets unchanged -- tail append
       // only.
-      const payload = new Float32Array(60);
+      const payload = new Float32Array(240);
       // worldViewProj = identity for this assertion (mat4 in [0..16))
       payload[0] = 1; // m00
       payload[5] = 1; // m11
@@ -133,7 +136,7 @@ describe('w4 view UBO 240 B std140 layout (AC-06, browser)', () => {
     // calculation.
     const inverseProjF32Index = VIEW_UBO_OFFSETS.inverseViewProj / 4;
     expect(inverseProjF32Index).toBe(44);
-    const payload = new Float32Array(60);
+    const payload = new Float32Array(240);
     // Place an identity mat4 at inverseViewProj slot [44..59]
     payload[44] = 1;
     payload[49] = 1;
@@ -145,6 +148,13 @@ describe('w4 view UBO 240 B std140 layout (AC-06, browser)', () => {
     expect(payload[59]).toBe(1);
   });
 
+  it.skipIf(!browserReady)('shadow tail keeps the directional carrier before spot matrices', () => {
+    expect(DIRECTIONAL_FILTER_OFFSET).toBe(126 * 4 + 8);
+    expect(SPOT_LIGHT_VIEW_PROJ_OFFSET).toBe(132 * 4);
+    expect(SPOT_LIGHT_VIEW_PROJ_OFFSET - DIRECTIONAL_FILTER_OFFSET).toBe(16);
+    expect(SPOT_LIGHT_VIEW_PROJ_OFFSET + 4 * 4 * 16).toBe(VIEW_UBO_BYTES - 176);
+  });
+
   it.skipIf(!browserReady)(
     'existing field offsets unchanged by tail append (AC-06 rear-append guarantee)',
     () => {