@forgeax/engine-runtime 0.1.2

package/src/__tests__/shadow-m3.dawn.test.ts

@@ -0,0 +1,288 @@
+// shadow-m3.dawn.test.ts -
+// feat-20260621-merge-directionallightshadow-into-directionallight / M3 / m3-t1.
+//
+// M3 wires the merged DirectionalLight's depthBias / normalBias / pcfKernelSize
+// into the View UBO tail (floats [126/127/128], bytes 504/508/512) and drives
+// the directional shadow bias + variable-width PCF loop from those uniforms
+// (lighting-directional.wgsl::_sampleShadowForCascade, D-1 / D-2). This test is
+// the RED gate for that wiring.
+//
+// AC anchor: requirements AC-03 (shadow params flow from the merged component to
+// the shader) + AC-08 (View UBO byte layout stays fixed: VIEW_PAYLOAD_FLOATS=148
+// / VIEW_UBO_BYTES=592 unchanged; append at tail). plan-strategy D-1 (directional
+// bias mapping: normalBias=slope, depthBias=floor), D-2 (variable-width PCF
+// driven by pcfKernelSize via the merged 5.3-production-shadow-demos AC-14
+// constant-trip-count loop), D-7 (host clamp pcfKernelSize into {1,3,5}).
+//
+// What is observable, and why these assertions:
+//   * The View UBO buffer is created UNIFORM | COPY_DST only (no COPY_SRC) and
+//     there is no debug accessor returning its bytes, so the float-slot
+//     placement cannot be asserted by GPU readback. The debugSampleShadowFactor
+//     probe is a SELF-CONTAINED shader (hardcoded bias + fixed 3x3 textureLoad)
+//     that never binds the View UBO, so it cannot observe pcfKernelSize either.
+//   * The shader-wiring RED gate is therefore asserted against the COMPOSED
+//     engine shader: _sampleShadowForCascade reads view.pcfKernelSize and runs
+//     a kernel/MAX_PCF_HALF constant-trip-count PCF loop (variant-free, merged
+//     from 5.3-production-shadow-demos AC-14), and derives the bias from
+//     view.normalBias / view.depthBias (D-1). Pre-wiring the composed default-standard-pbr shader
+//     has none of these tokens (RED); post-m3-t4 it does (GREEN). The composed
+//     WGSL is the single source the GPU compiles, so this is a faithful gate.
+//   * The merged component is exercised end-to-end on a real device: a single
+//     DirectionalLight (castShadow default true) + cube occluder + ground
+//     populates the shadow atlas, and debugSampleShadowFactor reports occluded
+//     positions shadowed and lit positions lit -- proving the merged shadow
+//     fields drive a working shadow pass.
+//   * Byte-layout invariance (AC-08) is asserted structurally: if the host
+//     payload float count or the WGSL struct byte size drifted out of sync, the
+//     pbr pipeline would fail to compile / validate and renderer.ready /
+//     renderer.draw would not return ok. A clean default-config render across
+//     the four clamped kernel sizes is the proxy for "VIEW_UBO_BYTES unchanged".
+
+import { World } from '@forgeax/engine-ecs';
+import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+import {
+  Camera,
+  DirectionalLight,
+  MeshFilter,
+  MeshRenderer,
+} from '@forgeax/engine-render/internal';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from '../index';
+import { drawPublished } from './draw-published';
+
+const WIDTH = 256;
+const HEIGHT = 256;
+const TEXTURE_USAGE_COPY_SRC = 0x01;
+const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
+const GROUND_SIZE = 20;
+
+const ENGINE_MANIFEST = await (async () => {
+  const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+  return buildEngineShaderManifest();
+})();
+const ENGINE_MANIFEST_URL = `data:application/json,${encodeURIComponent(
+  JSON.stringify(ENGINE_MANIFEST),
+)}`;
+
+// biome-ignore lint/suspicious/noExplicitAny: dawn-node detection guard
+const dawnReady = typeof navigator !== 'undefined' && (navigator as any).gpu !== undefined;
+
+/** The composed default-standard-pbr WGSL the GPU actually compiles. */
+function composedStandardPbr(): string {
+  const m = ENGINE_MANIFEST.materialShaders.find(
+    (s) => s.identifier === 'forgeax::default-standard-pbr',
+  );
+  if (m === undefined) throw new Error('default-standard-pbr not in engine manifest');
+  return m.composedWgsl;
+}
+
+function createMockCanvas(): { canvas: HTMLCanvasElement; getDevice: () => GPUDevice | undefined } {
+  let sharedDevice: GPUDevice | undefined;
+  const originalRequestAdapter = globalThis.navigator.gpu.requestAdapter.bind(
+    globalThis.navigator.gpu,
+  );
+  globalThis.navigator.gpu.requestAdapter = async (opts) => {
+    const rawAdapter = await originalRequestAdapter(opts);
+    if (rawAdapter === null) return rawAdapter;
+    const originalRequestDevice = rawAdapter.requestDevice.bind(rawAdapter);
+    rawAdapter.requestDevice = async (desc) => {
+      const dev = await originalRequestDevice(desc);
+      if (sharedDevice === undefined) sharedDevice = dev;
+      return dev;
+    };
+    return rawAdapter;
+  };
+  let renderTarget: GPUTexture | undefined;
+  const ensureRenderTarget = (device: GPUDevice, format: GPUTextureFormat): GPUTexture => {
+    if (renderTarget !== undefined) return renderTarget;
+    renderTarget = device.createTexture({
+      size: { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+      format,
+      usage: TEXTURE_USAGE_RENDER_ATTACHMENT | TEXTURE_USAGE_COPY_SRC,
+      viewFormats: ['rgba8unorm-srgb'],
+    });
+    return renderTarget;
+  };
+  const canvas = {
+    width: WIDTH,
+    height: HEIGHT,
+    getContext(kind: string): unknown {
+      if (kind !== 'webgpu') return null;
+      return {
+        configure(desc: { device: GPUDevice; format?: GPUTextureFormat }) {
+          ensureRenderTarget(desc.device, desc.format ?? 'rgba8unorm');
+        },
+        unconfigure() {},
+        getCurrentTexture(): GPUTexture {
+          if (renderTarget === undefined) {
+            if (sharedDevice === undefined)
+              throw new Error('render target requested before device captured');
+            return ensureRenderTarget(sharedDevice, 'rgba8unorm');
+          }
+          return renderTarget;
+        },
+      };
+    },
+    addEventListener() {},
+    removeEventListener() {},
+  } as unknown as HTMLCanvasElement;
+  return { canvas, getDevice: () => sharedDevice };
+}
+
+/**
+ * Cube occluder above a ground plane, lit by a near-vertical directional light.
+ * The camera looks down the -Z axis (orthographic) so the full scene is in the
+ * shadow atlas fit. `pcfKernelSize` is set on the single merged DirectionalLight.
+ */
+function buildShadowScene(world: World, pcfKernelSize: number): void {
+  const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
+  // Ground plane (flattened cube), top face at y=0. Empty MeshRenderer ->
+  // engine default standard material (shadow-receiving forward pass).
+  world
+    .spawn(
+      {
+        component: Transform,
+        data: {
+          pos: [0, -0.005, 0],
+          quat: [0, 0, 0, 1],
+          scale: [GROUND_SIZE, 0.01, GROUND_SIZE],
+        },
+      },
+      { component: MeshFilter, data: { assetHandle: cubeHandle } },
+      { component: MeshRenderer, data: {} },
+    )
+    .unwrap();
+
+  // Occluder cube, 2x2x2 centred at y=1.5 (bottom at y=0.5).
+  world
+    .spawn(
+      {
+        component: Transform,
+        data: { pos: [0, 1.5, 0], quat: [0, 0, 0, 1], scale: [2, 2, 2] },
+      },
+      { component: MeshFilter, data: { assetHandle: cubeHandle } },
+      { component: MeshRenderer, data: {} },
+    )
+    .unwrap();
+
+  world
+    .spawn({
+      component: DirectionalLight,
+      data: {
+        direction: [0.2, -0.98, 0],
+        color: [1, 1, 1],
+        intensity: 1.5,
+        // Single cascade so the cube/ground land in the tile-0 slot the probe
+        // samples (same migration the prior M2/M3 fixtures relied on).
+        cascadeCount: 1,
+        mapSize: 1024,
+        shadowDistance: 50,
+        pcfKernelSize,
+      },
+    })
+    .unwrap();
+
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 10], quat: [0, 0, 0, 1] } },
+      {
+        component: Camera,
+        data: {
+          projection: 1,
+          left: -5,
+          right: 5,
+          bottom: -5,
+          top: 5,
+          near: 0.1,
+          far: 100,
+          fov: 0,
+          aspect: 1,
+        } as Record<string, unknown> as never,
+      },
+    )
+    .unwrap();
+}
+
+describe('shadow M3 dawn: merged DirectionalLight shadow params -> View UBO + variable PCF', () => {
+  it.skipIf(!dawnReady)("'dawn-binding-missing' -- dawn.node binding injection failed", () => {
+    expect(dawnReady).toBe(true);
+  });
+
+  it('composed default-standard-pbr drives shadow bias + PCF from View uniforms (D-1/D-2)', () => {
+    const wgsl = composedStandardPbr();
+    // D-1: bias is derived from the View UBO's normalBias (slope) + depthBias
+    // (floor), replacing the prior hardcoded max(0.05*(1-N.L), 0.005).
+    expect(wgsl).toContain('normalBias');
+    expect(wgsl).toContain('depthBias');
+    // D-2: the directional PCF loop is driven by view.pcfKernelSize via a
+    // runtime-clamped kernel half-extent (constant trip count to MAX_PCF_HALF,
+    // per-iteration radius clip — the variant-free pattern merged from
+    // 5.3-production-shadow-demos AC-14), not a fixed 3x3.
+    expect(wgsl).toContain('pcfKernelSize');
+    // Composition may rename or fold local variables. The runtime width read
+    // and rounding are the textual contract; the pixel and all-kernel tests
+    // below prove the branch behavior through Dawn.
+    expect(wgsl).toMatch(/round\(/);
+  });
+
+  it.skipIf(!dawnReady)(
+    'merged DirectionalLight casts a shadow (occluded < lit) via debugSampleShadowFactor',
+    async () => {
+      const { canvas, getDevice } = createMockCanvas();
+      const renderer = await createRenderer(canvas, {}, { shaderManifestUrl: ENGINE_MANIFEST_URL });
+      expect(renderer.backend).toBe('webgpu');
+      const ready = await renderer.ready;
+      expect(ready.ok).toBe(true);
+
+      const world = new World();
+      buildShadowScene(world, 7);
+      world.update(1 / 60).unwrap();
+      const draw = drawPublished(renderer, world);
+      expect(draw.ok).toBe(true);
+      const device = getDevice();
+      if (device !== undefined) await device.queue.onSubmittedWorkDone();
+
+      // Occluded ground positions under the cube vs a lit position well outside
+      // the shadow. The probe reads the shadow atlas the merged component's
+      // shadow fields populated.
+      const occluded: [number, number, number][] = [
+        [0, 0, 0],
+        [0.5, 0, 0],
+      ];
+      const lit: [number, number, number][] = [[-4, 0, 0]];
+      const occRes = await renderer.debugSampleShadowFactor?.(occluded);
+      const litRes = await renderer.debugSampleShadowFactor?.(lit);
+      expect(occRes).not.toBeNull();
+      expect(litRes).not.toBeNull();
+      if (!occRes || !litRes) throw new Error('debugSampleShadowFactor returned null');
+
+      for (const r of occRes) expect(r.shadowFactor).toBeLessThan(0.5);
+      for (const r of litRes) expect(r.shadowFactor).toBeGreaterThan(0.9);
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    'all clamped kernel sizes render cleanly (View UBO byte layout intact, AC-08)',
+    async () => {
+      const { canvas, getDevice } = createMockCanvas();
+      const renderer = await createRenderer(canvas, {}, { shaderManifestUrl: ENGINE_MANIFEST_URL });
+      const ready = await renderer.ready;
+      expect(ready.ok).toBe(true);
+      const device = getDevice();
+
+      // Walk every host-clamp target {1,3,5} plus an over-cap value (9 -> 5);
+      // each must drive a valid View UBO write + draw without a structured
+      // RhiError / device loss. A byte layout out of sync with the WGSL struct
+      // would fail compile/validate.
+      for (const ks of [1, 3, 5, 9]) {
+        const world = new World();
+        buildShadowScene(world, ks);
+        world.update(1 / 60).unwrap();
+        const draw = drawPublished(renderer, world);
+        expect(draw.ok, `draw failed at pcfKernelSize=${ks}`).toBe(true);
+        if (device !== undefined) await device.queue.onSubmittedWorkDone();
+      }
+    },
+  );
+});

package/src/__tests__/shadow-mesh-ssbo-order.test.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const shadowPassPath = fileURLToPath(
+  new URL('../../../render/src/record/shadow-pass.ts', import.meta.url),
+);
+const shadowPass = readFileSync(shadowPassPath, 'utf8');
+
+function sourceAfter(signature: string): string {
+  const start = shadowPass.indexOf(signature);
+  expect(start).toBeGreaterThanOrEqual(0);
+  return shadowPass.slice(start);
+}
+
+function expectValidatedOrderedLoop(
+  signature: string,
+  indexName: string,
+  dynamicOffsetBindGroup: string,
+): void {
+  const body = sourceAfter(signature);
+  expect(body).toContain(
+    `for (let ${indexName} = 0; ${indexName} < validatedOrdered.length; ${indexName}++)`,
+  );
+  expect(body).toContain(`${dynamicOffsetBindGroup}, [${indexName} * MESH_PER_ENTITY_STRIDE]`);
+}
+
+function expectShadowEntriesLoop(signature: string, dynamicOffsetBindGroup: string): void {
+  const body = sourceAfter(signature);
+  expect(body).toContain('for (const { entry, validatedIndex: ei } of shadowEntries)');
+  expect(body).toContain(`${dynamicOffsetBindGroup}, [ei * MESH_PER_ENTITY_STRIDE]`);
+}
+
+describe('shadow mesh SSBO order', () => {
+  it('uses the upload order for directional, point, and spot shadow offsets', () => {
+    expectValidatedOrderedLoop(
+      'function recordShadowCasterDraws(',
+      'i',
+      'shadowPass.setBindGroup(2, shadowMeshBindGroup',
+    );
+    expectShadowEntriesLoop(
+      'export function recordPointShadowPass(',
+      'pass.setBindGroup(2, meshBindGroup',
+    );
+    expectShadowEntriesLoop(
+      'function recordSpotShadowGeometry(',
+      'pass.setBindGroup(2, meshBindGroup',
+    );
+  });
+
+  it('keeps directional candidate union out of legacy point/spot caster domains', () => {
+    const point = sourceAfter('export function recordPointShadowPass(');
+    const spot = sourceAfter('function recordSpotShadowGeometry(');
+    expect(shadowPass).toContain(
+      "buildMatchedRenderableIndices(c.dispatch, { LightMode: ['ShadowCaster'] })",
+    );
+    expect(point).toContain('const mainMembership = mainShadowMembership(c);');
+    expect(point).toContain('c.validatedShadowEntries ??');
+    expect(point).toContain('isMainShadowRenderable(entry, mainMembership)');
+    expect(spot).toContain('const mainMembership = mainShadowMembership(c);');
+    expect(spot).toContain('c.validatedShadowEntries ??');
+    expect(spot).toContain('isMainShadowRenderable(entry, mainMembership)');
+  });
+});

package/src/__tests__/shadow-probe-control-flow.dawn.test.ts

@@ -0,0 +1,264 @@
+import { describe, expect, it } from 'vitest';
+import { SHADOW_PROBE_WGSL } from '../../../render/src/renderer/renderer-factory';
+
+const dawnReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+const PROBE_MAX_COUNT = 64;
+const PROBE_LSM_UBO_BYTES = 352;
+const PROBE_OUTPUT_WIDTH = PROBE_MAX_COUNT;
+const PROBE_OUTPUT_ROW_BYTES = PROBE_OUTPUT_WIDTH * 16;
+const DEPTH_ATLAS_WIDTH = 64;
+const DEPTH_ATLAS_HEIGHT = 32;
+const DEPTH_TILE_SIZE = DEPTH_ATLAS_WIDTH / 2;
+
+const GPU_BUFFER_MAP_READ = 0x0001;
+const GPU_BUFFER_COPY_DST = 0x0008;
+const GPU_BUFFER_UNIFORM = 0x0040;
+const GPU_BUFFER_STORAGE = 0x0080;
+const GPU_TEXTURE_COPY_SRC = 0x0001;
+const GPU_TEXTURE_TEXTURE_BINDING = 0x0004;
+const GPU_TEXTURE_RENDER_ATTACHMENT = 0x0010;
+
+const DEPTH_WRITE_WGSL = `
+struct VsOut {
+  @builtin(position) position : vec4<f32>,
+};
+
+@vertex fn vs_main(@builtin(vertex_index) index : u32) -> VsOut {
+  var positions = array<vec2<f32>, 3>(
+    vec2<f32>(-1.0, -1.0),
+    vec2<f32>( 3.0, -1.0),
+    vec2<f32>(-1.0,  3.0),
+  );
+  var out : VsOut;
+  out.position = vec4<f32>(positions[index], 0.1, 1.0);
+  return out;
+}
+`;
+
+interface ProbeResult {
+  readonly shadowFactor: number;
+  readonly sampledDepth: number;
+  readonly cascadeIndex: number;
+  readonly receiverDepth: number;
+}
+
+function makeLightMatrix(): Float32Array {
+  const matrix = new Float32Array(16);
+  matrix[0] = 1;
+  matrix[5] = 1;
+  // Keep XY in clip space while pinning all receivers to a known depth.
+  matrix[10] = 0;
+  matrix[14] = 0.5;
+  matrix[15] = 1;
+  return matrix;
+}
+
+function makeIdentityMatrix(): Float32Array {
+  const matrix = new Float32Array(16);
+  matrix[0] = 1;
+  matrix[5] = 1;
+  matrix[10] = 1;
+  matrix[15] = 1;
+  return matrix;
+}
+
+async function runControlledProbe(): Promise<ProbeResult[]> {
+  const gpu = navigator.gpu;
+  const adapter = await gpu.requestAdapter();
+  if (adapter === null) throw new Error('no Dawn adapter');
+  const device = await adapter.requestDevice();
+
+  const shaderModule = device.createShaderModule({ code: SHADOW_PROBE_WGSL });
+  const pipeline = device.createRenderPipeline({
+    layout: 'auto',
+    vertex: { module: shaderModule, entryPoint: 'vs_main' },
+    fragment: {
+      module: shaderModule,
+      entryPoint: 'fs_main',
+      targets: [{ format: 'rgba32float' }],
+    },
+    primitive: { topology: 'triangle-list' },
+  });
+
+  const depthModule = device.createShaderModule({ code: DEPTH_WRITE_WGSL });
+  const depthPipeline = device.createRenderPipeline({
+    layout: 'auto',
+    vertex: { module: depthModule, entryPoint: 'vs_main' },
+    primitive: { topology: 'triangle-list' },
+    depthStencil: {
+      format: 'depth32float',
+      depthWriteEnabled: true,
+      depthCompare: 'less',
+    },
+  });
+
+  const depthTexture = device.createTexture({
+    size: { width: DEPTH_ATLAS_WIDTH, height: DEPTH_ATLAS_HEIGHT, depthOrArrayLayers: 1 },
+    format: 'depth32float',
+    usage: GPU_TEXTURE_TEXTURE_BINDING | GPU_TEXTURE_RENDER_ATTACHMENT,
+  });
+  const depthView = depthTexture.createView();
+  const depthEncoder = device.createCommandEncoder();
+  const depthPass = depthEncoder.beginRenderPass({
+    colorAttachments: [],
+    depthStencilAttachment: {
+      view: depthView,
+      depthLoadOp: 'clear',
+      depthStoreOp: 'store',
+      depthClearValue: 0.9,
+    },
+  });
+  depthPass.setPipeline(depthPipeline);
+  // Only sibling tile 1 contains a caster. Tile 0 stays at the clear depth.
+  depthPass.setViewport(0, 0, DEPTH_ATLAS_WIDTH, DEPTH_ATLAS_HEIGHT, 0, 1);
+  depthPass.setScissorRect(DEPTH_TILE_SIZE, 0, DEPTH_TILE_SIZE, DEPTH_TILE_SIZE);
+  depthPass.draw(3);
+  depthPass.end();
+  device.queue.submit([depthEncoder.finish()]);
+
+  const lsm = new Float32Array(PROBE_LSM_UBO_BYTES / 4);
+  const lightMatrix = makeLightMatrix();
+  const viewMatrix = makeIdentityMatrix();
+  lsm.set(lightMatrix, 0);
+  lsm.set(lightMatrix, 16);
+  lsm.set(lightMatrix, 32);
+  lsm.set(lightMatrix, 48);
+  lsm.set(viewMatrix, 64);
+  // Cascade 0 spans viewDepth < 10; cascade 1 ends at shadowDistance 15.
+  lsm[80] = 10;
+  lsm[81] = 15;
+  const lsmU32 = new Uint32Array(lsm.buffer);
+  lsmU32[84] = 2;
+  lsmU32[85] = 3;
+  lsm[86] = 0.2;
+
+  // Three probes are deliberately chosen to falsify three independent
+  // control-flow regressions:
+  //   1. local XY outside cascade 0 but inside atlas-space UV;
+  //   2. beyond the final split / shadowDistance;
+  //   3. inside the cascade-0 blend band with different sibling depth.
+  const positions = [
+    [1.25, 0, 0.5, 0],
+    [0, 0, -20, 0],
+    [0, 0, -9, 0],
+  ] as const;
+  const input = new Float32Array(PROBE_MAX_COUNT * 4);
+  for (let index = 0; index < positions.length; index += 1) {
+    const [x, y, z, bias] = positions[index] ?? [0, 0, 0, 0];
+    const base = index * 4;
+    input[base] = x;
+    input[base + 1] = y;
+    input[base + 2] = z;
+    input[base + 3] = bias;
+  }
+
+  const lsmBuffer = device.createBuffer({
+    size: PROBE_LSM_UBO_BYTES,
+    usage: GPU_BUFFER_UNIFORM | GPU_BUFFER_COPY_DST,
+  });
+  const inputBuffer = device.createBuffer({
+    size: input.byteLength,
+    usage: GPU_BUFFER_STORAGE | GPU_BUFFER_COPY_DST,
+  });
+  device.queue.writeBuffer(lsmBuffer, 0, lsm);
+  device.queue.writeBuffer(inputBuffer, 0, input);
+
+  const sampler = device.createSampler({
+    addressModeU: 'clamp-to-edge',
+    addressModeV: 'clamp-to-edge',
+    magFilter: 'linear',
+    minFilter: 'linear',
+    compare: 'less',
+  });
+  const bindGroup = device.createBindGroup({
+    layout: pipeline.getBindGroupLayout(0),
+    entries: [
+      { binding: 0, resource: { buffer: lsmBuffer } },
+      { binding: 1, resource: { buffer: inputBuffer } },
+      { binding: 2, resource: depthView },
+      { binding: 3, resource: sampler },
+    ],
+  });
+
+  const outputTexture = device.createTexture({
+    size: { width: PROBE_OUTPUT_WIDTH, height: 1, depthOrArrayLayers: 1 },
+    format: 'rgba32float',
+    usage: GPU_TEXTURE_COPY_SRC | GPU_TEXTURE_RENDER_ATTACHMENT,
+  });
+  const outputView = outputTexture.createView();
+  const staging = device.createBuffer({
+    size: PROBE_OUTPUT_ROW_BYTES,
+    usage: GPU_BUFFER_COPY_DST | GPU_BUFFER_MAP_READ,
+  });
+
+  const encoder = device.createCommandEncoder();
+  const pass = encoder.beginRenderPass({
+    colorAttachments: [
+      {
+        view: outputView,
+        loadOp: 'clear',
+        storeOp: 'store',
+        clearValue: { r: 1, g: 1, b: -1, a: 1 },
+      },
+    ],
+  });
+  pass.setPipeline(pipeline);
+  pass.setBindGroup(0, bindGroup);
+  pass.draw(6, positions.length);
+  pass.end();
+  encoder.copyTextureToBuffer(
+    { texture: outputTexture },
+    { buffer: staging, bytesPerRow: PROBE_OUTPUT_ROW_BYTES, rowsPerImage: 1 },
+    { width: PROBE_OUTPUT_WIDTH, height: 1, depthOrArrayLayers: 1 },
+  );
+  device.queue.submit([encoder.finish()]);
+  await staging.mapAsync(GPU_BUFFER_MAP_READ);
+  const readback = new Float32Array(staging.getMappedRange().slice(0));
+  staging.unmap();
+
+  const result: ProbeResult[] = [];
+  for (let index = 0; index < positions.length; index += 1) {
+    const base = index * 4;
+    result.push({
+      shadowFactor: readback[base] ?? 1,
+      sampledDepth: readback[base + 1] ?? 1,
+      cascadeIndex: Math.round(readback[base + 2] ?? -1),
+      receiverDepth: readback[base + 3] ?? 1,
+    });
+  }
+
+  staging.destroy();
+  outputTexture.destroy();
+  inputBuffer.destroy();
+  lsmBuffer.destroy();
+  depthTexture.destroy();
+  device.destroy();
+  return result;
+}
+
+describe('production shadow probe control-flow falsifiers', () => {
+  it.skipIf(!dawnReady)(
+    'rejects local-tile OOB, final-split OOB, and blends sibling tiles',
+    async () => {
+      const [localOob, finalSplitOob, blendBand] = await runControlledProbe();
+
+      // The local-tile point maps to atlas UV x=0.5625, where the sibling tile
+      // contains depth 0.1. A global-atlas guard would read that non-clear depth;
+      // the producer-local guard must fail closed before any texture read.
+      expect(localOob?.shadowFactor).toBe(1);
+      expect(localOob?.sampledDepth).toBe(1);
+      expect(localOob?.cascadeIndex).toBe(0);
+
+      expect(finalSplitOob?.cascadeIndex).toBe(-1);
+      expect(finalSplitOob?.shadowFactor).toBe(1);
+
+      // At viewDepth=9, split=10 and blend=0.2, t=0.5. Tile 0 is lit (0.9)
+      // and sibling tile 1 is blocked (0.1), so the exact production blend is
+      // 0.5. Removing the adjacent-layer sample or the mix makes this RED.
+      expect(blendBand?.cascadeIndex).toBe(0);
+      expect(blendBand?.shadowFactor).toBeCloseTo(0.5, 3);
+      expect(blendBand?.sampledDepth).toBeCloseTo(0.9, 3);
+    },
+  );
+});