@forgeax/engine-runtime 0.1.2

package/src/__tests__/dawn/ibl-compose.dawn.test.ts

@@ -0,0 +1,151 @@
+// ibl-compose.dawn.test.ts - feat-20260520-skylight-ibl-cubemap M3 / t17.
+//
+// Composes forgeax_pbr::ibl via naga_oil Composer (real wasm boundary) and
+// asserts that: (a) #import with a missing module reports shader-import-not-found,
+// (b) importing a pure-math helper from a stub ibl module composes + validates,
+// (c) the real ibl.wgsl (with pbr-style #import specifiers) composes and validates.
+//
+// Note: naga_oil's Composer inlines the #import-ed module into a naga::Module,
+// then naga's wgsl writer only emits functions that are actually called from the
+// entry. Entries must therefore call the imported function to keep it in the
+// writeback output.
+
+import { composeShader, parse } from '@forgeax/engine-naga';
+import { describe, expect, it } from 'vitest';
+
+const dawnReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+describe('t17 - ibl.wgsl naga_oil compose', () => {
+  it.skipIf(!dawnReady)(
+    '(a) compose with #import for an unregistered module fails with shader-import-not-found',
+    async () => {
+      const pbrEntry = [
+        '#import forgeax_pbr::ibl::{helperFn}',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  _ = helperFn(1.0);',
+        '  return vec4<f32>(1.0);',
+        '}',
+      ].join('\n');
+
+      await expect(composeShader(pbrEntry, {}, {})).rejects.toThrow(/shader-import-not-found/);
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b) compose with IBL stub module registered + entry calls it passes Naga validation',
+    async () => {
+      const iblSource = [
+        '#define_import_path forgeax_pbr::ibl',
+        '',
+        'fn radicalInverseVdC(bits: u32) -> f32 {',
+        '  var b: u32 = bits;',
+        '  b = (b << 16u) | (b >> 16u);',
+        '  b = ((b & 0x55555555u) << 1u) | ((b & 0xAAAAAAAAu) >> 1u);',
+        '  b = ((b & 0x33333333u) << 2u) | ((b & 0xCCCCCCCCu) >> 2u);',
+        '  b = ((b & 0x0F0F0F0Fu) << 4u) | ((b & 0xF0F0F0F0u) >> 4u);',
+        '  b = ((b & 0x00FF00FFu) << 8u) | ((b & 0xFF00FF00u) >> 8u);',
+        '  return f32(b) * 2.3283064365386963e-10;',
+        '}',
+      ].join('\n');
+
+      const pbrEntry = [
+        '#import forgeax_pbr::ibl::{radicalInverseVdC}',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  _ = radicalInverseVdC(42u);',
+        '  return vec4<f32>(1.0);',
+        '}',
+      ].join('\n');
+
+      const imports = { 'forgeax_pbr::ibl': iblSource };
+      const composed = await composeShader(pbrEntry, imports, {});
+
+      expect(composed.length).toBeGreaterThan(0);
+      expect(composed).toContain('radicalInverseVdC');
+
+      // Naga validation.
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(c) full ibl.wgsl-equivalent math helpers composes with entry calling them',
+    async () => {
+      // Equivalent to the real ibl.wgsl module structure: shared math
+      // helpers (radicalInverseVdC, hammersley, iblDGGX) plus sampleIblDiffuse
+      // and sampleIblSpecular runtime helpers. This exercises the same
+      // naga_oil composition path as the real ibl.wgsl without needing to
+      // fs.readFile / createRequire (node imports unavailable in the runtime
+      // package).
+      const iblSource = [
+        '#define_import_path forgeax_pbr::ibl',
+        '',
+        'const PI: f32 = 3.14159265;',
+        '',
+        'fn radicalInverseVdC(bits: u32) -> f32 {',
+        '  var b: u32 = bits;',
+        '  b = (b << 16u) | (b >> 16u);',
+        '  b = ((b & 0x55555555u) << 1u) | ((b & 0xAAAAAAAAu) >> 1u);',
+        '  b = ((b & 0x33333333u) << 2u) | ((b & 0xCCCCCCCCu) >> 2u);',
+        '  b = ((b & 0x0F0F0F0Fu) << 4u) | ((b & 0xF0F0F0F0u) >> 4u);',
+        '  b = ((b & 0x00FF00FFu) << 8u) | ((b & 0xFF00FF00u) >> 8u);',
+        '  return f32(b) * 2.3283064365386963e-10;',
+        '}',
+        '',
+        'fn hammersley(i: u32, N: u32) -> vec2<f32> {',
+        '  return vec2<f32>(f32(i) / f32(N), radicalInverseVdC(i));',
+        '}',
+        '',
+        'fn iblDGGX(nDotH: f32, roughness: f32) -> f32 {',
+        '  let a = roughness * roughness;',
+        '  let a2 = a * a;',
+        '  let f = (nDotH * a2 - nDotH) * nDotH + 1.0;',
+        '  return a2 / (max(PI * f * f, 1e-7));',
+        '}',
+        '',
+        'fn fresnelSchlickRoughness(cosTheta: f32, F0: vec3<f32>, roughness: f32) -> vec3<f32> {',
+        '  return F0 + (max(vec3<f32>(1.0 - roughness), F0) - F0) * pow(clamp(1.0 - cosTheta, 0.0, 1.0), 5.0);',
+        '}',
+        '',
+        'fn sampleIblDiffuse(normal: vec3<f32>, irradianceMap: texture_cube<f32>, irradianceSampler: sampler) -> vec3<f32> {',
+        '  return textureSample(irradianceMap, irradianceSampler, normal).rgb;',
+        '}',
+        '',
+        'fn sampleIblSpecular(normal: vec3<f32>, view: vec3<f32>, roughness: f32, F0: vec3<f32>, prefilterMap: texture_cube<f32>, prefilterSampler: sampler, brdfLut: texture_2d<f32>, brdfLutSampler: sampler) -> vec3<f32> {',
+        '  let NdotV = max(dot(normal, view), 0.001);',
+        '  let R = reflect(-view, normal);',
+        '  let mip = roughness * 4.0;',
+        '  let prefilteredColor = textureSampleLevel(prefilterMap, prefilterSampler, R, mip).rgb;',
+        '  let envBRDF = textureSample(brdfLut, brdfLutSampler, vec2<f32>(NdotV, roughness)).rg;',
+        '  let F = fresnelSchlickRoughness(NdotV, F0, roughness);',
+        '  return prefilteredColor * (F * envBRDF.r + envBRDF.g);',
+        '}',
+      ].join('\n');
+
+      // Entry calls a pure-math helper (radicalInverseVdC) which is trivially
+      // verifiable with toContain, and also references the real pbr.wgsl-style
+      // import path forgeax_pbr::ibl::{radicalInverseVdC} to prove the module ID
+      // is recognized by naga_oil.
+      const entry = [
+        '#import forgeax_pbr::ibl::{radicalInverseVdC}',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  _ = radicalInverseVdC(7u);',
+        '  return vec4<f32>(1.0);',
+        '}',
+      ].join('\n');
+
+      const imports = { 'forgeax_pbr::ibl': iblSource };
+      const composed = await composeShader(entry, imports, {});
+
+      expect(composed.length).toBeGreaterThan(0);
+      expect(composed).toContain('radicalInverseVdC');
+
+      // Validate with Naga.
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+});

package/src/__tests__/dawn/ibl-modules-compose.dawn.test.ts

@@ -0,0 +1,223 @@
+// ibl-modules-compose.dawn.test.ts -- feat-20260520-skylight-ibl-cubemap M3 / t41.
+//
+// Cross-file composition test for the 6-module ibl-* family. Each module
+// declares a unique #define_import_path; this test verifies that naga_oil
+// Composer can:
+//   (1) Register every module independently (no @group/@binding collision).
+//   (2) Compose ibl_shared + ibl_irradiance into a fragment entry that
+//       references ibl_irradiance helpers, exercising the texture_cube
+//       @group(1) binding path.
+//   (3) Compose ibl_shared + ibl_prefilter into a fragment entry, mirroring
+//       (2) but with the prefilter module's additional prefilterUniforms
+//       buffer to confirm dual-uniform @group(0) ordering.
+//   (4) Compose ibl_shared + ibl_sampling into a pbr-style entry that
+//       provides texture/sampler as function arguments (zero-binding
+//       runtime helper module).
+//
+// Red-phase: before t42..t47 land, the source files do not exist and every
+// it(...) below fails (readFileSync throws ENOENT). Green after the 6
+// modules exist + their imports compose cleanly.
+//
+// node:* are accessed via the established `await import(varId)` pattern
+// (renderer-draw-world.test.ts) so the runtime tsconfig does not need an
+// explicit `@types/node` types entry (which would regress brand-type
+// narrowing in createRenderer.ts).
+
+import { composeShader, parse } from '@forgeax/engine-naga';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+interface NodeFs {
+  readFileSync: (p: string, enc: string) => string;
+}
+interface NodePath {
+  resolve: (...parts: string[]) => string;
+  dirname: (p: string) => string;
+}
+interface NodeModule {
+  createRequire: (filename: string | URL) => { resolve: (id: string) => string };
+}
+
+const dawnReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+let srcDir!: string;
+let readSourceSync!: (file: string) => string;
+
+beforeAll(async () => {
+  const fsId = 'node:fs';
+  const pathId = 'node:path';
+  const moduleId = 'node:module';
+  const fs = (await import(/* @vite-ignore */ fsId)) as NodeFs;
+  const path = (await import(/* @vite-ignore */ pathId)) as NodePath;
+  const mod = (await import(/* @vite-ignore */ moduleId)) as NodeModule;
+  const req = mod.createRequire(import.meta.url);
+  const pkg = req.resolve('@forgeax/engine-shader/package.json');
+  srcDir = path.resolve(path.dirname(pkg), 'src');
+  readSourceSync = (file: string) => fs.readFileSync(path.resolve(srcDir, file), 'utf8');
+});
+
+describe('t41 (b) -- 6-module ibl-* family naga_oil composition', () => {
+  it.skipIf(!dawnReady)(
+    '(b1) ibl_shared composes alone (zero binding pure-math module)',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const entry = [
+        '#import forgeax_pbr::ibl_shared::{hammersley}',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  let h = hammersley(3u, 16u);',
+        '  return vec4<f32>(h, 0.0, 1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(entry, { 'forgeax_pbr::ibl_shared': shared }, {});
+      expect(composed).toContain('hammersley');
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b2) ibl_shared + ibl_irradiance compose (texture_cube @group(1))',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const irradiance = readSourceSync('ibl-irradiance.wgsl');
+      // The irradiance module declares its own @group(0) faceUniforms +
+      // @group(1) envCube + sampler. Compose by importing irradianceConvolve_fs
+      // as the entry directly -- naga_oil inlines the module sources, the
+      // composed output exposes the entry. We call it via a thin re-entry.
+      const entry = [
+        '#import forgeax_pbr::ibl_shared::{radicalInverseVdC}',
+        '#import forgeax_pbr::ibl_irradiance',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  _ = radicalInverseVdC(11u);',
+        '  return vec4<f32>(1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(
+        entry,
+        {
+          'forgeax_pbr::ibl_shared': shared,
+          'forgeax_pbr::ibl_irradiance': irradiance,
+        },
+        {},
+      );
+      expect(composed.length).toBeGreaterThan(0);
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b3) ibl_shared + ibl_prefilter compose (dual-uniform @group(0))',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const prefilter = readSourceSync('ibl-prefilter.wgsl');
+      const entry = [
+        '#import forgeax_pbr::ibl_shared::{hammersley}',
+        '#import forgeax_pbr::ibl_prefilter',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  _ = hammersley(0u, 1024u);',
+        '  return vec4<f32>(1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(
+        entry,
+        {
+          'forgeax_pbr::ibl_shared': shared,
+          'forgeax_pbr::ibl_prefilter': prefilter,
+        },
+        {},
+      );
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b4) ibl_shared + ibl_sampling compose (zero-binding runtime helper)',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const sampling = readSourceSync('ibl-sampling.wgsl');
+      // ibl_sampling exports sampleIblDiffuse/sampleIblSpecular which take
+      // texture/sampler as function arguments. The entry provides them via
+      // its own @group(1) bindings, mirroring how pbr.wgsl consumes the
+      // helper through its skylight @group(4).
+      const entry = [
+        '#import forgeax_pbr::ibl_sampling::{sampleIblDiffuse}',
+        '@group(1) @binding(0) var irradianceMap: texture_cube<f32>;',
+        '@group(1) @binding(1) var irradianceSampler: sampler;',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  let c = sampleIblDiffuse(vec3<f32>(0.0, 1.0, 0.0), vec4<f32>(0.0, 0.0, 0.0, 1.0), irradianceMap, irradianceSampler);',
+        '  return vec4<f32>(c, 1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(
+        entry,
+        {
+          'forgeax_pbr::ibl_shared': shared,
+          'forgeax_pbr::ibl_sampling': sampling,
+        },
+        {},
+      );
+      expect(composed).toContain('sampleIblDiffuse');
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b5) ibl_brdf_lut composes alone (no @group(1) external texture)',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const brdfLut = readSourceSync('ibl-brdf-lut.wgsl');
+      const entry = [
+        '#import forgeax_pbr::ibl_shared::{hammersley}',
+        '#import forgeax_pbr::ibl_brdf_lut',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  _ = hammersley(1u, 16u);',
+        '  return vec4<f32>(1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(
+        entry,
+        {
+          'forgeax_pbr::ibl_shared': shared,
+          'forgeax_pbr::ibl_brdf_lut': brdfLut,
+        },
+        {},
+      );
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b6) ibl_shared + ibl_equirect_to_cube compose (texture_2d @group(1))',
+    async () => {
+      const shared = readSourceSync('ibl-shared.wgsl');
+      const equirect = readSourceSync('ibl-equirect-to-cube.wgsl');
+      const entry = [
+        '#import forgeax_pbr::ibl_shared::{radicalInverseVdC}',
+        '#import forgeax_pbr::ibl_equirect_to_cube',
+        '@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(0.0); }',
+        '@fragment fn fs() -> @location(0) vec4<f32> {',
+        '  _ = radicalInverseVdC(5u);',
+        '  return vec4<f32>(1.0);',
+        '}',
+      ].join('\n');
+      const composed = await composeShader(
+        entry,
+        {
+          'forgeax_pbr::ibl_shared': shared,
+          'forgeax_pbr::ibl_equirect_to_cube': equirect,
+        },
+        {},
+      );
+      const parsed = await parse(composed);
+      expect(parsed).not.toBeNull();
+    },
+  );
+});

package/src/__tests__/dawn/ibl-precompute-readback.dawn.test.ts

@@ -0,0 +1,241 @@
+// t51 (M3.5) -- dawn 4-pass IBL precompute readback (red-phase).
+//
+// Real GPU (dawn-node / webgpu native binding) test: feeds a 4x2 rgba16float
+// all-ones equirect into uploadCubemapFromEquirect, then reads back one
+// pixel from each of the 4 produced textures. All 4 pixels must be
+// non-zero -- a zero readback means the GPU pass never ran (round-1
+// counter-as-dispatch-proxy regression).
+//
+// Red phase: before t52/t53 wire real createIblPipelines + runIblPrecompute,
+// the cubemap / irradiance / prefilter / brdfLut textures are created but
+// never drawn into, so every readback pixel is vec4(0).
+//
+// Green phase: t52/t53 land 4 real render passes + queue.submit; readback
+// pixels carry non-zero values (white equirect -> bright cube -> non-zero
+// irradiance / prefilter / brdfLut).
+
+import { World } from '@forgeax/engine-ecs';
+import { composeShader } from '@forgeax/engine-naga';
+import {
+  GpuResourceStore,
+  getOrCreateIblCache,
+  setIblComposedShaders,
+} from '@forgeax/engine-render/internal';
+import { ok } from '@forgeax/engine-rhi';
+import type { EquirectAsset, TextureFormat } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+const mockCaps = {
+  backendKind: 'webgpu' as const,
+  compute: true,
+  timestampQuery: false,
+  timestampPeriodNanoseconds: null,
+  indirectDrawing: false,
+  textureCompressionBc: false,
+  textureCompressionEtc2: false,
+  textureCompressionAstc: false,
+  multiDrawIndirect: false,
+  pushConstants: false,
+  textureBindingArray: false,
+  samplerAliasing: false,
+  firstInstanceIndirect: false,
+  storageBuffer: true,
+  storageTexture: false,
+  rgba16floatRenderable: true,
+  rg11b10ufloatRenderable: false,
+  float32Filterable: false,
+  maxColorAttachments: 8,
+};
+
+// feat-20260601-gpu-resource-store-extraction M1 (D-3 falsifiable anchor): a
+// single store._uploadCubemapFromEquirect(world, srcHandle, srcPod) returns the
+// cube handle, and store.getCubemapGpuTexture(cubeHandle) reads it back -- the
+// single-call contract is preserved. The cube POD register-relay is injected
+// at configureGpuDevice and mints via world.allocSharedRef (the store holds no
+// registry reference, D-3).
+
+// Load + compose the 6 ibl-* WGSL modules into the 4 composed entry shaders
+// that createIblPipelines consumes. Mirrors what vite-plugin-shader does at
+// build-time for the browser/runtime path; the dawn test stands in for
+// vite-plugin-shader so the readback receives non-placeholder pipelines.
+async function composeIblShadersForDawn(): Promise<void> {
+  const fsId = 'node:fs';
+  const pathId = 'node:path';
+  const urlId = 'node:url';
+  const fs = (await import(/* @vite-ignore */ fsId)) as {
+    readFileSync: (p: string, enc: string) => string;
+  };
+  const pathMod = (await import(/* @vite-ignore */ pathId)) as {
+    resolve: (...parts: string[]) => string;
+    dirname: (p: string) => string;
+  };
+  const url = (await import(/* @vite-ignore */ urlId)) as {
+    fileURLToPath: (u: string) => string;
+  };
+  const here = url.fileURLToPath(import.meta.url);
+  // Resolve packages/shader/src/ relative to this test file
+  // (packages/runtime/src/__tests__/dawn/).
+  const shaderSrc = pathMod.resolve(pathMod.dirname(here), '..', '..', '..', '..', 'shader', 'src');
+  const read = (name: string) => fs.readFileSync(pathMod.resolve(shaderSrc, name), 'utf8');
+  const sharedSrc = read('ibl-shared.wgsl');
+  const equirectSrc = read('ibl-equirect-to-cube.wgsl');
+  const irradianceSrc = read('ibl-irradiance.wgsl');
+  const prefilterSrc = read('ibl-prefilter.wgsl');
+  const brdfLutSrc = read('ibl-brdf-lut.wgsl');
+  // ibl-shared is the only #import the per-pass modules reference.
+  const imports = { 'forgeax_pbr::ibl_shared': sharedSrc };
+  const [equirectToCube, irradiance, prefilter, brdfLut] = await Promise.all([
+    composeShader(equirectSrc, imports, {}),
+    composeShader(irradianceSrc, imports, {}),
+    composeShader(prefilterSrc, imports, {}),
+    composeShader(brdfLutSrc, imports, {}),
+  ]);
+  setIblComposedShaders({ equirectToCube, irradiance, prefilter, brdfLut });
+}
+
+const dawnReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+function makeWhiteEquirect(): EquirectAsset {
+  // 4x2 rgba16float, all 1.0 (HDR white). 16-bit float 1.0 = 0x3C00 = 15360.
+  const w = 4;
+  const h = 2;
+  const data = new Uint8Array(w * h * 8);
+  const dv = new DataView(data.buffer);
+  for (let i = 0; i < w * h * 4; i++) {
+    dv.setUint16(i * 2, 0x3c00, true);
+  }
+  return {
+    kind: 'equirect',
+    width: w,
+    height: h,
+    format: 'rgba16float' as TextureFormat,
+    data,
+    colorSpace: 'linear',
+  };
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: native GPUDevice has minimal typing here
+async function readbackRgba16f(device: any, texture: any, arrayLayer: number, mipLevel: number) {
+  // Read one pixel from (0,0) of (face=arrayLayer, mip=mipLevel).
+  const bytesPerRow = 256;
+  const buffer = device.createBuffer({
+    size: bytesPerRow,
+    usage: 0x0001 | 0x0008, // MAP_READ | COPY_DST
+  });
+  const encoder = device.createCommandEncoder({ label: 'ibl-readback' });
+  encoder.copyTextureToBuffer(
+    { texture, mipLevel, origin: { x: 0, y: 0, z: arrayLayer } },
+    { buffer, bytesPerRow },
+    { width: 1, height: 1, depthOrArrayLayers: 1 },
+  );
+  device.queue.submit([encoder.finish()]);
+  await buffer.mapAsync(0x0001 /* MAP_READ */);
+  const range = buffer.getMappedRange();
+  const dv = new DataView(range.slice(0));
+  buffer.unmap();
+  const f16ToF32 = (u16: number) => {
+    const sign = (u16 & 0x8000) >> 15;
+    const exp = (u16 & 0x7c00) >> 10;
+    const frac = u16 & 0x03ff;
+    if (exp === 0) return (sign ? -1 : 1) * 2 ** -14 * (frac / 1024);
+    if (exp === 0x1f) return frac ? Number.NaN : (sign ? -1 : 1) * Number.POSITIVE_INFINITY;
+    return (sign ? -1 : 1) * 2 ** (exp - 15) * (1 + frac / 1024);
+  };
+  return [
+    f16ToF32(dv.getUint16(0, true)),
+    f16ToF32(dv.getUint16(2, true)),
+    f16ToF32(dv.getUint16(4, true)),
+    f16ToF32(dv.getUint16(6, true)),
+  ];
+}
+
+describe('t51 (M3.5) -- dawn IBL 4-pass non-zero readback', () => {
+  it.skipIf(!dawnReady)(
+    'AC-04/05/06: equirect / irradiance / prefilter / brdfLut readback pixels are non-zero',
+    async () => {
+      // Compose ibl-* WGSL into 4 entry shaders before the upload. In
+      // production this happens at vite-plugin-shader build-time and the
+      // runtime calls setIblComposedShaders with the composed bundle;
+      // dawn-node tests stand in for vite-plugin-shader by composing on
+      // demand via @forgeax/engine-naga.
+      await composeIblShadersForDawn();
+      // biome-ignore lint/suspicious/noExplicitAny: dynamic global navigator typed minimally
+      const adapter = await (navigator as any).gpu.requestAdapter();
+      const device = await adapter.requestDevice();
+
+      const store = new GpuResourceStore();
+      const world = new World();
+      const equirect = makeWhiteEquirect();
+      const equirectHandle = world.allocSharedRef('EquirectAsset', equirect);
+
+      // We pass the raw GPUDevice directly so the runtime exercises the
+      // same dawn path that user-mesh-upload.dawn.test.ts uses. The cube POD
+      // register-relay is injected here (D-3).
+      store.configureGpuDevice(
+        // biome-ignore lint/suspicious/noExplicitAny: dawn device shape
+        device as any,
+        // biome-ignore lint/suspicious/noExplicitAny: dawn device shape
+        async (d: any, desc: { code: string; label?: string }) => {
+          const mod = d.createShaderModule({ code: desc.code, label: desc.label });
+          // biome-ignore lint/suspicious/noExplicitAny: matching shim Result shape
+          return { ok: true, value: mod, unwrap: () => mod, unwrapOr: () => mod } as any;
+        },
+        (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
+        mockCaps,
+      );
+
+      // Single call returns the cube handle (D-3 single-call contract). The
+      // projection method is @internal (private) after feat-20260630 M2 / w11;
+      // the dawn test reaches it through the store internals.
+      // biome-ignore lint/suspicious/noExplicitAny: private method access for the dawn IBL readback probe
+      const result = await (store as any)._uploadCubemapFromEquirect(
+        world,
+        equirectHandle,
+        equirect,
+      );
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+
+      const cubeHandle = result.value;
+      // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture
+      const cubeTexture = store.getCubemapGpuTexture(cubeHandle as any);
+      expect(cubeTexture).toBeDefined();
+
+      // feat-20260612 M3 / w11 (1c76c1b9): GpuResourceStore handle maps now
+      // hold the GpuTexture wrapper (`{handle, isDestroyed, destroy()}`).
+      // dawn-node `copyTextureToBuffer` consumes the raw GPUTexture handle,
+      // so the wrapper unwrap goes via `.handle` here. The IBL cache slots
+      // below still hold raw textures (the ibl/IblPipelineCache wrapping is
+      // OOS for this feat -- D-8 / OOS-10).
+      // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture
+      const cubeRaw = (cubeTexture as any).handle;
+
+      // (a) equirect-to-cube face 0 center pixel != 0
+      const cubePx = await readbackRgba16f(device, cubeRaw, 0, 0);
+      expect(cubePx.some((c) => c !== 0)).toBe(true);
+
+      // (b) irradiance, (c) prefilter, (d) brdfLut: the textures live on
+      // IblPipelineCache after t52/t53. Read via cache slots.
+      const cache = getOrCreateIblCache(device);
+      // biome-ignore lint/suspicious/noExplicitAny: cache slots typed any
+      const irrTex = (cache as any).irradianceTexture;
+      // biome-ignore lint/suspicious/noExplicitAny: cache slots typed any
+      const prefTex = (cache as any).prefilterTexture;
+      // biome-ignore lint/suspicious/noExplicitAny: cache slots typed any
+      const brdfTex = (cache as any).brdfLutTexture;
+      expect(irrTex).toBeDefined();
+      expect(prefTex).toBeDefined();
+      expect(brdfTex).toBeDefined();
+
+      const irrPx = await readbackRgba16f(device, irrTex, 0, 0);
+      expect(irrPx.some((c) => c !== 0)).toBe(true);
+
+      const prefPx = await readbackRgba16f(device, prefTex, 0, 0);
+      expect(prefPx.some((c) => c !== 0)).toBe(true);
+
+      const brdfPx = await readbackRgba16f(device, brdfTex, 0, 0);
+      expect(brdfPx.some((c) => c !== 0)).toBe(true);
+    },
+    60_000,
+  );
+});