@forgeax/engine-runtime 0.1.23 → 0.1.25

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

@@ -126,7 +126,7 @@ async function readbackRgba16f(
   texture: GPUTexture,
   arrayLayer: number,
   mipLevel: number,
-): Promise<number[]> {
+): Promise<{ values: number[]; rawBytes: number[] }> {
   // Read one pixel from (0,0) of (face=arrayLayer, mip=mipLevel).
   const bytesPerRow = 256;
   const buffer = device.createBuffer({
@@ -142,7 +142,8 @@ async function readbackRgba16f(
   device.queue.submit([encoder.finish()]);
   await buffer.mapAsync(0x0001 /* MAP_READ */);
   const range = buffer.getMappedRange();
-  const dv = new DataView(range.slice(0));
+  const raw = new Uint8Array(range.slice(0));
+  const dv = new DataView(raw.buffer);
   buffer.unmap();
   const f16ToF32 = (u16: number) => {
     const sign = (u16 & 0x8000) >> 15;
@@ -152,12 +153,129 @@ async function readbackRgba16f(
     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)),
-  ];
+  return {
+    values: [
+      f16ToF32(dv.getUint16(0, true)),
+      f16ToF32(dv.getUint16(2, true)),
+      f16ToF32(dv.getUint16(4, true)),
+      f16ToF32(dv.getUint16(6, true)),
+    ],
+    rawBytes: [...raw.slice(0, 8)],
+  };
+}
+
+interface TextureReadbackSpec {
+  readonly label: string;
+  readonly texture: GPUTexture;
+  readonly width: number;
+  readonly height: number;
+  readonly faces: number;
+  readonly mipLevels: number;
+  readonly identity: string;
+}
+
+/**
+ * Submit all subresource copies before mapping any staging buffer. This keeps
+ * the readback observational: no producer pass is interrupted by a map/wait.
+ */
+async function assertFiniteTextureRgba16f(
+  device: GPUDevice,
+  spec: TextureReadbackSpec,
+): Promise<void> {
+  const bytesPerPixel = 8;
+  const parts: Array<{
+    readonly buffer: GPUBuffer;
+    readonly width: number;
+    readonly height: number;
+    readonly face: number;
+    readonly mip: number;
+    readonly rowPitch: number;
+  }> = [];
+  const encoder = device.createCommandEncoder({ label: `${spec.label}-full-readback` });
+  for (let mip = 0; mip < spec.mipLevels; mip += 1) {
+    const width = Math.max(1, spec.width >> mip);
+    const height = Math.max(1, spec.height >> mip);
+    const rowPitch = Math.ceil((width * bytesPerPixel) / 256) * 256;
+    for (let face = 0; face < spec.faces; face += 1) {
+      const buffer = device.createBuffer({
+        label: `${spec.label}-readback-face${face}-mip${mip}`,
+        size: rowPitch * height,
+        usage: 0x0001 | 0x0008,
+      });
+      encoder.copyTextureToBuffer(
+        { texture: spec.texture, mipLevel: mip, origin: { x: 0, y: 0, z: face } },
+        { buffer, bytesPerRow: rowPitch },
+        { width, height, depthOrArrayLayers: 1 },
+      );
+      parts.push({ buffer, width, height, face, mip, rowPitch });
+    }
+  }
+  device.queue.submit([encoder.finish()]);
+  await Promise.all(parts.map((part) => part.buffer.mapAsync(0x0001)));
+  try {
+    for (const part of parts) {
+      const raw = new Uint8Array(part.buffer.getMappedRange()).slice();
+      const view = new DataView(raw.buffer);
+      for (let y = 0; y < part.height; y += 1) {
+        for (let x = 0; x < part.width; x += 1) {
+          const offset = y * part.rowPitch + x * bytesPerPixel;
+          for (let channel = 0; channel < 4; channel += 1) {
+            const value = f16ToF32(view.getUint16(offset + channel * 2, true));
+            if (!Number.isFinite(value)) {
+              const rawBytes = [...raw.slice(offset, offset + bytesPerPixel)];
+              throw new Error(
+                `${spec.label} non-finite sample at texture=${spec.identity}, face=${part.face}, mip=${part.mip}, x=${x}, y=${y}; rawBytes=${rawBytes.join(',')}`,
+              );
+            }
+          }
+        }
+      }
+    }
+  } finally {
+    for (const part of parts) {
+      part.buffer.unmap();
+      part.buffer.destroy();
+    }
+  }
+}
+
+function f16ToF32(u16: number): 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);
+}
+
+async function loadPhysicalGuidEquirect(): Promise<EquirectAsset> {
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const crypto = await import('node:crypto');
+  const here = path.dirname(new URL(import.meta.url).pathname);
+  const guid = '019e4a26-3c29-7420-af5d-20f2724a16b0';
+  const bodyPath = path.resolve(
+    here,
+    '../../../../../apps/hello/physical-material/dist/assets',
+    `${guid}-body.bin`,
+  );
+  const raw = (fs.readFileSync as unknown as (path: string) => Uint8Array)(bodyPath);
+  const data = new Uint8Array(raw.byteLength);
+  data.set(raw);
+  const digest = crypto.createHash('sha256').update(data).digest('hex');
+  const expected = '391ac77feea42745a6ae6b12d4da46bed90e8af4721525f4def0882c10cd8084';
+  if (digest !== expected) throw new Error(`physical HDR body hash mismatch: ${digest}`);
+  console.error(
+    `[ibl-diagnostic] ${JSON.stringify({ sourceGuid: guid, bodyPath, bodySha256: digest, width: 1600, height: 800, format: 'rgba16float', deviceGeneration: 0 })}`,
+  );
+  return {
+    kind: 'equirect',
+    width: 1600,
+    height: 800,
+    format: 'rgba16float',
+    data,
+    colorSpace: 'linear',
+  };
 }
 
 describe('t51 (M3.5) -- dawn IBL 4-pass non-zero readback', () => {
@@ -184,7 +302,10 @@ describe('t51 (M3.5) -- dawn IBL 4-pass non-zero readback', () => {
       const scope = DeviceScope.create(0, 'ibl-dawn-test');
       store.bindDeviceScope(scope);
       const world = new World();
-      const equirect = makeWhiteEquirect();
+      const equirect =
+        process.env.FORGEAX_IBL_REAL_SOURCE === '1'
+          ? await loadPhysicalGuidEquirect()
+          : makeWhiteEquirect();
       const equirectHandle = world.allocSharedRef('EquirectAsset', equirect);
 
       // The production path receives the opaque RhiDevice and the same
@@ -220,7 +341,16 @@ describe('t51 (M3.5) -- dawn IBL 4-pass non-zero readback', () => {
 
       // (a) equirect-to-cube face 0 center pixel != 0
       const cubePx = await readbackRgba16f(rawDevice, cubeRaw, 0, 0);
-      expect(cubePx.some((c) => c !== 0)).toBe(true);
+      expect(cubePx.values.some((c) => c !== 0)).toBe(true);
+      await assertFiniteTextureRgba16f(rawDevice, {
+        label: 'base-cube',
+        texture: cubeRaw,
+        width: Math.min(equirect.width, equirect.height),
+        height: Math.min(equirect.width, equirect.height),
+        faces: 6,
+        mipLevels: 1,
+        identity: 'cubemap-source',
+      });
 
       // (b) irradiance, (c) prefilter, (d) brdfLut: the textures live on
       // IblPipelineCache after t52/t53. Read opaque cache slots through the
@@ -234,16 +364,53 @@ describe('t51 (M3.5) -- dawn IBL 4-pass non-zero readback', () => {
       expect(irrTex).toBeDefined();
       expect(prefTex).toBeDefined();
       expect(brdfTex).toBeDefined();
-      if (irrTex === undefined || prefTex === undefined || brdfTex === undefined) return;
+      expect(cache.prefilterFaceViewsByMip).toBeDefined();
+      if (
+        irrTex === undefined ||
+        prefTex === undefined ||
+        brdfTex === undefined ||
+        cache.prefilterFaceViewsByMip === undefined
+      )
+        return;
 
-      const irrPx = await readbackRgba16f(rawDevice, rawTexture(irrTex), 0, 0);
-      expect(irrPx.some((c) => c !== 0)).toBe(true);
+      const irrRaw = rawTexture(irrTex);
+      const irrPx = await readbackRgba16f(rawDevice, irrRaw, 0, 0);
+      expect(irrPx.values.some((c) => c !== 0)).toBe(true);
+      await assertFiniteTextureRgba16f(rawDevice, {
+        label: 'irradiance',
+        texture: irrRaw,
+        width: 32,
+        height: 32,
+        faces: 6,
+        mipLevels: 1,
+        identity: 'ibl-irradiance-cube',
+      });
 
-      const prefPx = await readbackRgba16f(rawDevice, rawTexture(prefTex), 0, 0);
-      expect(prefPx.some((c) => c !== 0)).toBe(true);
+      const prefRaw = rawTexture(prefTex);
+      const prefPx = await readbackRgba16f(rawDevice, prefRaw, 0, 0);
+      expect(prefPx.values.some((c) => c !== 0)).toBe(true);
+      await assertFiniteTextureRgba16f(rawDevice, {
+        label: 'prefilter',
+        texture: prefRaw,
+        width: 128,
+        height: 128,
+        faces: 6,
+        mipLevels: cache.prefilterFaceViewsByMip.length,
+        identity: 'ibl-prefilter-cube',
+      });
 
-      const brdfPx = await readbackRgba16f(rawDevice, rawTexture(brdfTex), 0, 0);
-      expect(brdfPx.some((c) => c !== 0)).toBe(true);
+      const brdfRaw = rawTexture(brdfTex);
+      const brdfPx = await readbackRgba16f(rawDevice, brdfRaw, 0, 0);
+      expect(brdfPx.values.some((c) => c !== 0)).toBe(true);
+      await assertFiniteTextureRgba16f(rawDevice, {
+        label: 'brdf-lut',
+        texture: brdfRaw,
+        width: 256,
+        height: 256,
+        faces: 1,
+        mipLevels: 1,
+        identity: 'ibl-brdf-lut',
+      });
     },
     60_000,
   );

package/src/__tests__/dawn/instances-uniform-fallback.dawn.test.ts

@@ -1,28 +1,10 @@
-// instances-uniform-fallback.dawn.test.ts -- feat-20260604-instances-per-instance-transform-shader-group3-bin
-// M1 / w6.
-//
-// AC-07: storage-buffer path + uniform-fallback path both compile and render
-// correctly for <=128 instances.
-//
-// Primary path: dawn-node renders <=128 instances through the normal storage
-// buffer path (caps.storageBuffer===true on dawn) and asserts frames are
-// non-clear (proves the storage variant renders).
-//
-// Degraded path (research R-C partial): dawn-node always has
-// caps.storageBuffer===true, so we cannot force the uniform-fallback variant
-// at the GPU level. Instead, we verify that:
-//   (a) The uniform-fallback #else form `var<uniform> instances : array<InstanceData, 128>`
-//       is present in common.wgsl (source-level structural check).
-//   (b) The variant count stays at 2 (verified by w1 unit test).
-//   (c) A non-trivial Instances render (<=128) works on the storage path.
-//
-// This is the best-effort degraded path per research R-C: "if dawn cannot
-// construct caps.storageBuffer===false, fall back to a vitest unit that
-// asserts the #else uniform array<..,128> form compiles, with reason
-// recorded."
+// World-authored Instances render through storage and uniform bindings on Dawn.
+// The restricted RHI advertises no storage buffers while retaining the real
+// WebGPU device, shader compiler, validation and pixel readback. This proves
+// the uniform lane and its 128-instance chunks, not WebGL2 backend parity.
 
 import type { MaterialAsset } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
+import { beforeAll, describe, expect, it } from 'vitest';
 import { drawPublished } from '../draw-published';
 
 // Source-level structural check: common.wgsl must carry both the storage
@@ -45,7 +27,16 @@ const STORAGE_PATTERN =
 const UNIFORM_PATTERN =
   /@group\(3\)\s+@binding\(0\)\s+var<uniform>\s+instances\s*:\s*array<InstanceData,\s*128>/;
 
-describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () => {
+describe('World Instances storage and uniform submission', () => {
+  let ENGINE_MANIFEST_URL_W6: string;
+  beforeAll(async () => {
+    // Shader production is fixture setup; keep the render assertion's 30s
+    // deadline independent of a cold compiler/manifest build.
+    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+    const manifest = await buildEngineShaderManifest();
+    ENGINE_MANIFEST_URL_W6 = `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
+  }, 180_000);
+
   it('(a) common.wgsl declares uniform-fallback array<InstanceData,128> under #else', async () => {
     const fsId = 'node:fs';
     const pathId = 'node:path';
@@ -88,39 +79,41 @@ describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () =
     expect(commonSrc).toMatch(/localFromInstance\s*:\s*mat4x4<f32>/);
   });
 
-  // (b) deg-path rationale: dawn-node always has caps.storageBuffer===true, so
-  // the uniform-fallback path cannot be exercised at the GPU level in this
-  // dawn test. The uniform-fallback variant is structurally verified via:
-  //   - w1 source-level variant=2 unit test (AC-11)
-  //   - w6 (a) source-level uniform array<..,128> form check above
-  //   - naga_oil compiles both variants at build-time (vite-plugin-shader)
-  // Restore as a real `it()` if a dawn-side uniform-fallback path becomes
-  // reachable (feat-20260608-ci-time-cut converted from `expect(true)`).
-  it.todo('(b) deg-path rationale recorded: dawn-node always storageBuffer=true');
-
-  it('(c) storage path renders Instances (dawn smoke integration)', async () => {
+  it.each([
+    { storage: true, grid: 8 },
+    { storage: false, grid: 8 },
+    { storage: false, grid: 12 },
+  ])('renders $grid x $grid instances with storage=$storage', async ({ storage, grid }) => {
     const dawnAvailable = typeof globalThis.navigator?.gpu?.requestAdapter === 'function';
     if (!dawnAvailable) {
       throw new Error('dawn-node navigator.gpu not injected; vitest.setup-webgpu.ts regressed');
     }
 
-    // Render <=128 instances on the storage path and assert non-clear output.
-    // This proves the storage-buffer variant of @group(3) instances works
-    // end-to-end on dawn.
-
     const { World } = await import('@forgeax/engine-ecs');
+    const { rhi } = await import('@forgeax/engine-rhi-webgpu');
+    const restrictedRhi: typeof rhi = {
+      ...rhi,
+      async requestAdapter(...args) {
+        const adapter = await rhi.requestAdapter(...args);
+        if (!adapter.ok) return adapter;
+        const requestDevice = adapter.value.requestDevice.bind(adapter.value);
+        adapter.value.requestDevice = async (options) => {
+          const result = await requestDevice(options);
+          if (result.ok && !storage)
+            Object.defineProperty(result.value, 'caps', {
+              value: { ...result.value.caps, storageBuffer: false, compute: false },
+            });
+          return result;
+        };
+        return adapter;
+      },
+    };
     const { AssetRegistry, HANDLE_CUBE } = await import('@forgeax/engine-assets-runtime');
     const { Camera, MeshRenderer } = await import('@forgeax/engine-render');
     const { Instances } = await import('@forgeax/engine-render');
     const { constructRuntimeRendererHost } = await import('../../renderer-host');
     const { MeshFilter } = await import('@forgeax/engine-render');
     const { Transform } = await import('@forgeax/engine-scene');
-    const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
-    const ENGINE_MANIFEST_W6 = await buildEngineShaderManifest();
-    const ENGINE_MANIFEST_URL_W6 = `data:application/json,${encodeURIComponent(
-      JSON.stringify(ENGINE_MANIFEST_W6),
-    )}`;
-
     const W6_WIDTH = 256;
     const W6_HEIGHT = 256;
 
@@ -132,15 +125,20 @@ describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () =
       const originalRequestDevice = rawAdapter.requestDevice.bind(rawAdapter);
       rawAdapter.requestDevice = async (desc) => {
         const dev = await originalRequestDevice(desc);
-        if (sharedDevice === undefined) sharedDevice = dev;
+        if (sharedDevice === undefined) {
+          sharedDevice = dev;
+          dev.pushErrorScope('validation');
+        }
         return dev;
       };
       return rawAdapter;
     };
 
     let renderTarget: GPUTexture | undefined;
+    let targetFormat: GPUTextureFormat = 'rgba8unorm';
     const ensureTarget = (device: GPUDevice, format: GPUTextureFormat): GPUTexture => {
       if (renderTarget !== undefined) return renderTarget;
+      targetFormat = format;
       renderTarget = device.createTexture({
         size: { width: W6_WIDTH, height: W6_HEIGHT, depthOrArrayLayers: 1 },
         format,
@@ -177,15 +175,18 @@ describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () =
     try {
       host = await constructRuntimeRendererHost(
         mockCanvas,
-        {},
+        { rhi: restrictedRhi },
         { shaderManifestUrl: ENGINE_MANIFEST_URL_W6 },
       );
     } finally {
       globalThis.navigator.gpu.requestAdapter = origReq;
     }
-    expect(host.ok).toBe(true);
     if (!host.ok) throw host.error;
     const { renderer, assets } = host.value;
+    const errors: string[] = [];
+    renderer.subscribe((event) => {
+      if (event.kind === 'error') errors.push(JSON.stringify(event.error));
+    });
     expect(renderer.inspect().state).toBe('alive');
     expect(assets).toBeInstanceOf(AssetRegistry);
 
@@ -201,9 +202,8 @@ describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () =
       values: { baseColor: [0.9, 0.2, 0.2, 1], metallic: 0, roughness: 0.5 },
     } as MaterialAsset;
 
-    // Build ~60 instances (well under 128 uniform cap), 2D grid
-    const GRID = 8;
-    const COUNT = GRID * GRID; // 64
+    const GRID = grid;
+    const COUNT = GRID * GRID;
     const SP = 3.0;
     const transforms = new Float32Array(COUNT * 16);
     let idx = 0;
@@ -295,18 +295,45 @@ describe('w6 -- AC-07 storage+uniform variant test (degraded best-effort)', () =
     readbackBuf.unmap();
     readbackBuf.destroy();
 
-    // Sample multiple positions — the 8x8 grid should fill a substantial
-    // portion of the frame. Center should NOT be clear-color.
-    const cx = W6_WIDTH >> 1;
-    const cy = W6_HEIGHT >> 1;
-    const readPixel = (px: number, py: number): [number, number, number] => {
-      const off = py * bytesPerRow + px * 4;
-      return [bytes[off + 2] ?? 0, bytes[off + 1] ?? 0, bytes[off + 0] ?? 0];
-    };
-    const [cr, cg, cb] = readPixel(cx, cy);
-    // Clear color is ~(13, 13, 20) in sRGB bytes. Center should be
-    // significantly different (red cubes).
-    const distFromClear = Math.sqrt((cr - 13) ** 2 + (cg - 13) ** 2 + (cb - 20) ** 2);
-    expect(distFromClear).toBeGreaterThan(30);
+    expect(errors).toEqual([]);
+    expect((await device.popErrorScope())?.message).toBeUndefined();
+
+    // Count actual red material pixels; comparing against guessed clear bytes
+    // could pass an empty frame because the target applies sRGB conversion.
+    let redPixels = 0;
+    for (let y = 0; y < W6_HEIGHT; y++) {
+      for (let x = 0; x < W6_WIDTH; x++) {
+        const offset = y * bytesPerRow + x * 4;
+        const r = bytes[offset + (targetFormat.startsWith('bgra') ? 2 : 0)] ?? 0;
+        const g = bytes[offset + 1] ?? 0;
+        const b = bytes[offset + (targetFormat.startsWith('bgra') ? 0 : 2)] ?? 0;
+        if (r > g + 30 && r > b + 30) redPixels++;
+      }
+    }
+    expect(redPixels).toBeGreaterThan(COUNT * 2);
+    // The last row crosses the 128-instance boundary for the 12x12 case.
+    // Verify its last matrix reaches a distinct screen location, not a
+    // duplicate of the first chunk or merely some non-clear geometry.
+    const edge = ((GRID - 1) / 2) * SP * 0.3;
+    const ndcEdge = edge / (25 * Math.tan(Math.PI / 8));
+    const lastX = Math.round(((1 + ndcEdge) * W6_WIDTH) / 2);
+    const lastY = Math.round(((1 - ndcEdge) * W6_HEIGHT) / 2);
+    let lastInstancePixels = 0;
+    for (let y = lastY - 3; y <= lastY + 3; y++) {
+      for (let x = lastX - 3; x <= lastX + 3; x++) {
+        const offset = y * bytesPerRow + x * 4;
+        const r = bytes[offset + (targetFormat.startsWith('bgra') ? 2 : 0)] ?? 0;
+        const g = bytes[offset + 1] ?? 0;
+        const b = bytes[offset + (targetFormat.startsWith('bgra') ? 0 : 2)] ?? 0;
+        if (r > g + 30 && r > b + 30) lastInstancePixels++;
+      }
+    }
+    expect(lastInstancePixels).toBeGreaterThan(0);
+    if (!storage) {
+      const residency = renderer.inspect().instanceCollections[0];
+      expect(residency?.lane).toBe(COUNT > 128 ? 'chunked-uniform' : 'direct-uniform');
+      expect(residency?.uploadedBytes).toBe(0);
+    }
+    await renderer.dispose();
   });
 });

package/src/__tests__/dawn/material-alpha.dawn.test.ts

@@ -22,6 +22,7 @@ const ENGINE_MANIFEST = await (async () => {
   return buildEngineShaderManifest();
 })();
 const ENGINE_MANIFEST_URL = `data:application/json,${encodeURIComponent(JSON.stringify(ENGINE_MANIFEST))}`;
+const LIGHTWEIGHT_DAWN = process.env.FORGEAX_DAWN_LIGHTWEIGHT === '1';
 
 interface AlphaCase {
   readonly caseId: string;
@@ -92,6 +93,16 @@ const CASES: readonly AlphaCase[] = [
   },
 ];
 
+const DAWN_CASES = LIGHTWEIGHT_DAWN
+  ? CASES.filter((testCase) =>
+      [
+        'material-alpha-rgba-factor',
+        'material-alpha-mask-explicit',
+        'material-alpha-blend',
+      ].includes(testCase.caseId),
+    )
+  : CASES;
+
 function textureBytes(color: readonly [number, number, number, number]): Uint8Array {
   return Uint8Array.from(color.map((channel) => Math.round(channel * 255)));
 }
@@ -224,13 +235,12 @@ async function captureCase(testCase: AlphaCase): Promise<[number, number, number
         }
       : { cullMode: 'none' as const };
   const material = Materials.standard({
-    baseColor: [
+    baseColor: Materials.srgb([
       testCase.baseColor[0],
       testCase.baseColor[1],
       testCase.baseColor[2],
       testCase.baseAlpha,
-    ],
-    colorSpace: 'srgb',
+    ]),
     castShadow: false,
     metallic: 0,
     roughness: 1,
@@ -281,7 +291,10 @@ function expectedVisible(testCase: AlphaCase): boolean {
 }
 
 describe('M2 runtime PBR alpha readback', () => {
-  for (const testCase of CASES) {
+  // The browser parity gate still closes all seven alpha cases. Dawn keeps
+  // one opaque, one mask, and one blend boundary on overloaded PR runners;
+  // local/nightly runs retain the complete threshold matrix.
+  for (const testCase of DAWN_CASES) {
     it(`${testCase.caseId}: Materials.standard single draw is observable`, async () => {
       const actual = await captureCase(testCase);
       const expected = testCase.clear.map((channel) => Math.round(channel * 255));

package/src/__tests__/dawn/material-cooked-fixture.dawn.test.ts

@@ -22,9 +22,10 @@ type CookedRecord = {
 };
 
 type MaterialRow = {
+  readonly guid: string;
   readonly kind: 'material';
   readonly payload: {
-    readonly role?: string;
+    readonly parent?: string;
     readonly cooked?: CookedRecord;
   };
 };
@@ -41,24 +42,45 @@ const fixture = JSON.parse(
   ),
 ) as { readonly assets: readonly MaterialRow[] };
 
+const materialRows = fixture.assets.filter((asset) => asset.kind === 'material');
+const root = materialRows.find((asset) => asset.payload.parent === undefined);
+const derived = materialRows.find((asset) => asset.payload.parent === root?.guid);
+
 describe('custom-shader cooked MaterialAsset fixture', () => {
-  it('keeps browser and Dawn on the same key, bytes, and values', () => {
-    const root = fixture.assets.find((asset) => asset.payload.role === 'root');
-    const derived = fixture.assets.find((asset) => asset.payload.role === 'derived');
+  it('keeps browser and Dawn on the same cooked payload with the child override', () => {
     expect(root?.payload.cooked).toBeDefined();
     expect(derived?.payload.cooked).toBeDefined();
+
+    const cookedRecords = [root?.payload.cooked, derived?.payload.cooked];
+    for (const cooked of cookedRecords) {
+      expect(cooked).toBeDefined();
+      expect(cooked?.artifact?.digest).toMatch(/^sha256:/);
+      expect(cooked?.artifact?.digest).toBe(cooked?.artifactDigest);
+      expect(cooked?.receipt?.schemaVersion).toBe('material-cook/3');
+      expect(cooked?.receipt?.identity?.layoutIdentity).toMatch(/^sha256-/);
+      expect(cooked?.receipt?.identity?.programIdentity).toMatch(/^sha256:/);
+      expect(cooked?.receipt?.identity?.pipelineIdentity).toMatch(/^sha256:/);
+      expect(cooked?.receipt?.identity?.cookIdentity).toMatch(/^sha256:/);
+      expect(cooked?.receipt?.identity?.compilerFingerprint).toMatch(/^sha256-/);
+    }
     expect(derived?.payload.cooked?.specializationKey).toBe(
       root?.payload.cooked?.specializationKey,
     );
     expect(derived?.payload.cooked?.artifactDigest).toBe(root?.payload.cooked?.artifactDigest);
-    expect(derived?.payload.cooked?.artifact.bytes).toEqual(root?.payload.cooked?.artifact.bytes);
-    expect(derived?.payload.cooked?.resolved?.values).toEqual(
-      root?.payload.cooked?.resolved?.values,
-    );
+    expect(derived?.payload.cooked?.artifact?.bytes).toEqual(root?.payload.cooked?.artifact?.bytes);
+    expect(root?.payload.cooked?.resolved?.values).toMatchObject({
+      baseColor: [0.95, 0.45, 0.2, 1],
+      time: 0,
+      speed: 2,
+    });
+    expect(derived?.payload.cooked?.resolved?.values).toMatchObject({
+      baseColor: [0.2, 0.55, 0.95, 1],
+      time: 0,
+      speed: 2,
+    });
   });
 
   it('keeps cooked layout identity and authored coordinate transforms', () => {
-    const root = fixture.assets.find((asset) => asset.payload.role === 'root');
     const cooked = root?.payload.cooked;
     expect(cooked?.receipt?.schemaVersion).toBe('material-cook/3');
     expect(cooked?.receipt?.identity?.layoutIdentity).toMatch(/^sha256-/);

package/src/__tests__/derive-bgl-integration.test.ts

@@ -50,7 +50,7 @@ const standardPbrSchema: readonly ParamSchemaEntry[] = [
   { name: 'occlusionStrength', type: 'f32', default: 1 },
   { name: 'alphaCutoff', type: 'f32', default: 0 },
   { name: 'clearcoat', type: 'f32', default: 0 },
-  { name: 'clearcoatRoughness', type: 'f32', default: 0.5 },
+  { name: 'clearcoatRoughness', type: 'f32', default: 1 },
   { name: 'baseColorTexture', type: 'texture2d' },
   { name: 'metallicRoughnessTexture', type: 'texture2d' },
   { name: 'normalTexture', type: 'texture2d' },
@@ -202,12 +202,12 @@ const defaultStandardPbrSchema: readonly ParamSchemaEntry[] = [
   { name: 'occlusionStrength', type: 'f32', default: 1 },
   { name: 'alphaCutoff', type: 'f32', default: 0 },
   { name: 'clearcoat', type: 'f32', default: 0 },
-  { name: 'clearcoatRoughness', type: 'f32', default: 0.5 },
-  { name: 'specularTint', type: 'vec3', default: [1, 1, 1] },
+  { name: 'clearcoatRoughness', type: 'f32', default: 1 },
+  { name: 'specularColor', type: 'vec3', default: [1, 1, 1] },
   { name: 'baseColorTexture', type: 'texture2d' },
   { name: 'metallicRoughnessTexture', type: 'texture2d' },
   { name: 'normalTexture', type: 'texture2d' },
-  { name: 'specularTintTexture', type: 'texture2d' },
+  { name: 'specularColorTexture', type: 'texture2d' },
 ];
 
 describe('built-in PBR derive+injection regression fence (M1 w1)', () => {
@@ -234,7 +234,7 @@ describe('built-in PBR derive+injection regression fence (M1 w1)', () => {
     expect(out.textureFieldNames.has('baseColorTexture')).toBe(true);
     expect(out.textureFieldNames.has('metallicRoughnessTexture')).toBe(true);
     expect(out.textureFieldNames.has('normalTexture')).toBe(true);
-    expect(out.textureFieldNames.has('specularTintTexture')).toBe(true);
+    expect(out.textureFieldNames.has('specularColorTexture')).toBe(true);
 
     // sampler map: each texture has a paired sampler.
     expect(out.samplerForTexture.size).toBe(4);
@@ -243,7 +243,7 @@ describe('built-in PBR derive+injection regression fence (M1 w1)', () => {
       'metallicRoughnessTexture_sampler',
     );
     expect(out.samplerForTexture.get('normalTexture')).toBe('normalTexture_sampler');
-    expect(out.samplerForTexture.get('specularTintTexture')).toBe('specularTintTexture_sampler');
+    expect(out.samplerForTexture.get('specularColorTexture')).toBe('specularColorTexture_sampler');
   });
 
   it('w1 full pipeline: derive + ibl injection + lightmap injection = 20 entries dense 0..19', () => {
@@ -337,7 +337,7 @@ const parallax4TextureSchema: readonly ParamSchemaEntry[] = [
   { name: 'baseColorTexture', type: 'texture2d' },
   { name: 'metallicRoughnessTexture', type: 'texture2d' },
   { name: 'normalTexture', type: 'texture2d' },
-  { name: 'specularTintTexture', type: 'texture2d' },
+  { name: 'specularColorTexture', type: 'texture2d' },
   { name: 'heightTexture', type: 'texture2d' },
 ];
 
@@ -354,7 +354,7 @@ describe('5-texture custom schema derive: heightTexture binding + injection shif
     expect(out.bglEntries.length).toBe(11);
 
     // heightTexture is the 5th texture: sampler at binding 9, texture at binding 10.
-    // (after baseColor 1/2, MR 3/4, normal 5/6, specular tint 7/8).
+    // (after baseColor 1/2, MR 3/4, and normal 5/6).
     const heightSampler = out.bglEntries[9];
     const heightTexture = out.bglEntries[10];
     expect(heightSampler?.binding).toBe(9);