@forgeax/engine-runtime 0.1.2

package/src/__tests__/extract-frames-reset.test.ts

@@ -0,0 +1,158 @@
+// m2-t2: extractFrames resetForFrame invocation count + bone slice isolation (TDD red).
+//
+// Test AC-08:
+//   1) resetForFrame is called exactly once per frame (spy count assertion).
+//   2) Dual-world bone slices are disjoint (worldA slice vs worldB slice
+//      do not overlap), proving the skinPaletteAllocator's sequential-
+//      allocation-with-single-reset strategy correctly isolates per-world
+//      skin data without cross-world interleaving.
+//
+// Since extractFrame currently owns resetForFrame internally (M1 state),
+// we verify the expected M2 behavior:
+//   - extractFrame after M2-i2 does NOT call resetForFrame internally
+//   - extractFrames calls resetForFrame exactly once at entry
+//   - Per-world sequential allocation of skin palette slices yields
+//     non-overlapping byte ranges when two worlds both have skinned meshes.
+//
+// Anchors:
+//   plan-tasks.json m2-t2
+//   plan-strategy D-2
+//   research Finding 2
+//   requirements AC-08
+
+import { describe, expect, it } from 'vitest';
+
+// ── Skin palette allocator stub ──────────────────────────────────────────────
+
+interface SliceDescriptor {
+  jointCount: number;
+  byteOffset: number;
+  buffer: Uint8Array;
+}
+
+class StubSkinPaletteAllocator {
+  public resetCount = 0;
+  private nextByteOffset = 0;
+
+  resetForFrame(): void {
+    this.resetCount += 1;
+    this.nextByteOffset = 0;
+  }
+
+  allocateSlice(jointCount: number): SliceDescriptor {
+    const offset = this.nextByteOffset;
+    // Each joint = 4x4 float mat4 = 16 floats = 64 bytes
+    const byteLength = jointCount * 64;
+    this.nextByteOffset += byteLength;
+    return {
+      jointCount,
+      byteOffset: offset,
+      buffer: new Uint8Array(byteLength),
+    };
+  }
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe('extractFrames resetForFrame call count + bone slice isolation (m2-t2, AC-08)', () => {
+  // ── AC-08-a: resetForFrame call count == 1 per frame ─────────────────────
+
+  it('AC-08: resetForFrame is called exactly once when using extractFrames entry-point pattern', () => {
+    const allocator = new StubSkinPaletteAllocator();
+
+    // Simulate extractFrames pattern: one reset, then two per-world extracts
+    allocator.resetForFrame();
+
+    // Simulate worldA extract — allocate 3 joints (192 bytes)
+    const sliceA = allocator.allocateSlice(3);
+    expect(sliceA.byteOffset).toBe(0);
+    expect(sliceA.jointCount).toBe(3);
+
+    // Simulate worldB extract — allocate 2 joints (128 bytes)
+    const sliceB = allocator.allocateSlice(2);
+    expect(sliceB.byteOffset).toBe(192); // 3 * 64
+    expect(sliceB.jointCount).toBe(2);
+
+    // Reset count is exactly 1
+    expect(allocator.resetCount).toBe(1);
+  });
+
+  it('AC-08: calling resetForFrame twice would clear the cursor (anti-pattern guard)', () => {
+    const allocator = new StubSkinPaletteAllocator();
+
+    // First frame
+    allocator.resetForFrame();
+    allocator.allocateSlice(3);
+    expect(allocator.resetCount).toBe(1);
+
+    // If reset were called again mid-frame (the old extractFrame behavior),
+    // the cursor would restart at 0, overwriting the first world's slices
+    allocator.resetForFrame();
+    const sliceAfterSecondReset = allocator.allocateSlice(2);
+    // After second reset, byteOffset is 0 again — worldA's data would be overwritten
+    expect(sliceAfterSecondReset.byteOffset).toBe(0);
+    expect(allocator.resetCount).toBe(2);
+  });
+
+  // ── AC-08-b: Dual-world bone slice isolation ───────────────────────────────
+
+  it('AC-08: dual-world bone slices are disjoint (no overlap)', () => {
+    const allocator = new StubSkinPaletteAllocator();
+
+    // extractFrames pattern: one reset, then per-world allocation
+    allocator.resetForFrame();
+
+    const worldASlice = allocator.allocateSlice(3); // 3 joints = 192 bytes, offset 0
+    const worldBSlice = allocator.allocateSlice(2); // 2 joints = 128 bytes, offset 192
+
+    // Slices should not overlap
+    const aEnd = worldASlice.byteOffset + worldASlice.jointCount * 64;
+    const bStart = worldBSlice.byteOffset;
+    const bEnd = worldBSlice.byteOffset + worldBSlice.jointCount * 64;
+
+    expect(aEnd).toBeLessThanOrEqual(bStart);
+    expect(bStart).toBeGreaterThanOrEqual(aEnd);
+
+    // Additional verification: total allocation is contiguous
+    expect(bEnd).toBe(5 * 64); // (3 + 2) * 64 = 320 bytes
+  });
+
+  it('AC-08: three worlds with skin yields three non-overlapping slices', () => {
+    const allocator = new StubSkinPaletteAllocator();
+
+    allocator.resetForFrame();
+
+    const slice0 = allocator.allocateSlice(4); // 256 bytes, offset 0
+    const slice1 = allocator.allocateSlice(1); // 64 bytes, offset 256
+    const slice2 = allocator.allocateSlice(2); // 128 bytes, offset 320
+
+    // Verify disjoint ranges
+    const end0 = slice0.byteOffset + slice0.jointCount * 64;
+    const end1 = slice1.byteOffset + slice1.jointCount * 64;
+    const end2 = slice2.byteOffset + slice2.jointCount * 64;
+
+    expect(end0).toBeLessThanOrEqual(slice1.byteOffset);
+    expect(end1).toBeLessThanOrEqual(slice2.byteOffset);
+    expect(end2).toBe(7 * 64); // (4 + 1 + 2) * 64 = 448
+
+    expect(allocator.resetCount).toBe(1);
+  });
+
+  it('AC-08: zero-joint alloc in one world does not block the other', () => {
+    const allocator = new StubSkinPaletteAllocator();
+
+    allocator.resetForFrame();
+
+    const sliceA = allocator.allocateSlice(3); // 192 bytes, offset 0
+    const sliceB = allocator.allocateSlice(0); // 0 bytes, offset 192
+    const sliceC = allocator.allocateSlice(1); // 64 bytes, offset 192
+
+    expect(sliceA.byteOffset).toBe(0);
+    expect(sliceB.byteOffset).toBe(192);
+    expect(sliceB.jointCount).toBe(0);
+    expect(sliceC.byteOffset).toBe(192);
+    expect(sliceC.jointCount).toBe(1);
+
+    expect(allocator.resetCount).toBe(1);
+  });
+});

package/src/__tests__/extract-record-no-hardcoded-texture-fields.test.ts

@@ -0,0 +1,92 @@
+// extract-record-no-hardcoded-texture-fields.test.ts
+//
+// feat-20260621-learn-render-5-5-parallax-mapping-demo-aligned-wit M2 / w4
+//
+// Grep gate (AC-06 (1)): after the M2 SSOT refactor, the extract + record
+// stages must NOT resolve / validate / bind the user-region material textures
+// one field at a time. The user-region texture set is the single source of
+// truth `derive(paramSchema).textureFieldNames`; extract iterates it (w7) and
+// record assembles the user-region bind group from it (w8). A residual
+// per-field hardcoded read (`pv.baseColorTexture`, a fixed `binding: 2` slot
+// keyed to `submeshMaterial.normalTexture`, ...) means the SSOT collapse did
+// not actually happen — the 4th texture (heightTexture) would silently fall
+// through.
+//
+// Scope of the gate — the three USER-REGION texture fields only:
+//   baseColorTexture / metallicRoughnessTexture / normalTexture /
+//   specularTintTexture / emissiveTexture / occlusionTexture
+// These are the fields `derive(default-standard-pbr).textureFieldNames`
+// produces and that w7/w8 route through iteration.
+//
+// Deliberately NOT gated (legitimate residual naming):
+//   - engine-owned IBL bindings: these remain outside the material schema and
+//     are assembled by the injection path; material textures are not exempt.
+//   - USER_REGION_TEXTURE_FIELDS in derive-paramschema.ts: the 3-field
+//     register-time under-declaration validator (charter P3 safety net from
+//     the 4.3 blending regression). Orthogonal to binding; lives in a
+//     different file and is explicitly exempt (requirements-decisions F-1).
+//
+// RED before w7/w8 (extract resolves pv.baseColorTexture one-by-one; record
+// binds binding 2/4/6 keyed to submeshMaterial.<field>); GREEN after.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const EXTRACT_SRC = fileURLToPath(
+  new URL('../../../render/src/render-system-extract.ts', import.meta.url),
+);
+const RECORD_SRC = fileURLToPath(
+  new URL('../../../render/src/record/main-pass-material.ts', import.meta.url),
+);
+
+const USER_REGION_FIELDS = [
+  'baseColorTexture',
+  'metallicRoughnessTexture',
+  'normalTexture',
+  'specularTintTexture',
+  'emissiveTexture',
+  'occlusionTexture',
+] as const;
+
+/** Strip `//` line comments and block comments so commented prose never trips the gate. */
+function stripComments(source: string): string {
+  return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+}
+
+describe('extract/record have no per-field hardcoding of the user-region textures (M2 w4)', () => {
+  it('extract does not resolve user-region textures via per-field `pv.<field>` reads', () => {
+    const src = stripComments(readFileSync(EXTRACT_SRC, 'utf8'));
+    for (const field of USER_REGION_FIELDS) {
+      // `pv.baseColorTexture` / `pv["baseColorTexture"]` member reads off the
+      // values object are the hardcoded per-field resolve pattern w7
+      // replaces with a loop over derive().textureFieldNames.
+      const dotForm = new RegExp(`pv\\.${field}\\b`);
+      const bracketForm = new RegExp(`pv\\[['"]${field}['"]\\]`);
+      expect(dotForm.test(src), `extract still reads pv.${field} (per-field hardcode)`).toBe(false);
+      expect(bracketForm.test(src), `extract still reads pv["${field}"] (per-field hardcode)`).toBe(
+        false,
+      );
+    }
+  });
+
+  it('extract derives coordinate fields from the effective schema', () => {
+    const src = stripComments(readFileSync(EXTRACT_SRC, 'utf8'));
+    // The runtime owner may expose the effective schema through either the
+    // admitted projection or the compatibility-derived interface. Keep the
+    // gate about the contract (iterate the projection's texture set), not an
+    // implementation spelling that would reject the owner path.
+    expect(src).toMatch(/(?:derivedMaterialInterface|derivedInterface)\.textureFieldNames/);
+  });
+
+  it('record does not bind user-region textures via per-field `submeshMaterial.<field>` reads', () => {
+    const src = stripComments(readFileSync(RECORD_SRC, 'utf8'));
+    for (const field of USER_REGION_FIELDS) {
+      const memberForm = new RegExp(`submeshMaterial\\.${field}\\b`);
+      expect(
+        memberForm.test(src),
+        `record still reads submeshMaterial.${field} (per-field hardcode)`,
+      ).toBe(false);
+    }
+  });
+});

package/src/__tests__/fog-producer-manifest.ts

@@ -0,0 +1,162 @@
+export type FogProducerCase = {
+  readonly id: string;
+  readonly sourceFile: string;
+  readonly entryPoint: string;
+  readonly domain:
+    | 'urp-scene'
+    | 'hdrp-deferred'
+    | 'hdrp-forward'
+    | 'skybox'
+    | 'sprite'
+    | 'text'
+    | 'vfx';
+  readonly rayPolicy:
+    | 'perspective-world'
+    | 'orthographic-plane'
+    | 'inverse-view-projection'
+    | 'camera-far';
+  readonly alphaPolicy: 'preserve';
+};
+
+export const FOG_PRODUCER_MANIFEST_VERSION = 1 as const;
+
+export const FOG_PRODUCER_MANIFEST = [
+  {
+    id: 'urp-pbr-opaque',
+    sourceFile: 'default-standard-pbr.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'urp-scene',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'urp-pbr-masked',
+    sourceFile: 'default-standard-pbr.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'urp-scene',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'urp-pbr-skin',
+    sourceFile: 'default-standard-pbr-skin.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'urp-scene',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'urp-pbr-morph',
+    sourceFile: 'default-standard-pbr.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'urp-scene',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'urp-pbr-instances',
+    sourceFile: 'default-standard-pbr.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'urp-scene',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'urp-unlit',
+    sourceFile: 'unlit.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'urp-scene',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'hdrp-deferred',
+    sourceFile: 'hdrp-deferred-lighting.wgsl',
+    entryPoint: 'fs_lighting',
+    domain: 'hdrp-deferred',
+    rayPolicy: 'inverse-view-projection',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'hdrp-forward',
+    sourceFile: 'default-standard-pbr.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'hdrp-forward',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'transparent',
+    sourceFile: 'default-standard-pbr.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'hdrp-forward',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'sprite',
+    sourceFile: 'sprite.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'sprite',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'text',
+    sourceFile: 'msdf-text.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'text',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'skybox',
+    sourceFile: 'skybox.wgsl',
+    entryPoint: 'skybox_fs',
+    domain: 'skybox',
+    rayPolicy: 'camera-far',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'vfx-billboard',
+    sourceFile: 'vfx-render/billboard.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'vfx',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'vfx-mesh',
+    sourceFile: 'vfx-render/mesh.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'vfx',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'vfx-ribbon',
+    sourceFile: 'vfx-render/ribbon.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'vfx',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'vfx-trail',
+    sourceFile: 'vfx-render/trail.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'vfx',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+  {
+    id: 'vfx-beam',
+    sourceFile: 'vfx-render/beam.wgsl',
+    entryPoint: 'fs_main',
+    domain: 'vfx',
+    rayPolicy: 'perspective-world',
+    alphaPolicy: 'preserve',
+  },
+] as const satisfies readonly FogProducerCase[];
+
+export const FOG_PRODUCER_IDS = FOG_PRODUCER_MANIFEST.map((producer) => producer.id);

package/src/__tests__/fog-producer-pixel-probe.ts

@@ -0,0 +1,263 @@
+import type { FogProducerCase } from './fog-producer-manifest';
+
+type ManifestEntry = {
+  readonly hash?: string;
+  readonly wgsl?: string;
+};
+
+type MaterialManifestEntry = {
+  readonly identifier: string;
+  readonly composedWgsl: string;
+  readonly variants?: readonly { readonly composedWgsl: string }[];
+};
+
+export type FogProbeManifest = {
+  readonly entries: readonly ManifestEntry[];
+  readonly materialShaders: readonly MaterialManifestEntry[];
+};
+
+export type FogPixel = readonly [number, number, number, number];
+
+export type FogRaySample = {
+  readonly origin: readonly [number, number, number];
+  readonly direction: readonly [number, number, number];
+  readonly distance: number;
+};
+
+export type FogProducerPixelCapture = (producer: FogProducerCase) => Promise<{
+  readonly disabled: FogPixel;
+  readonly enabled: FogPixel;
+  readonly ray: FogRaySample;
+}>;
+
+export type FogProducerPixelEvidence = {
+  readonly producerId: string;
+  readonly shaderIdentifier: string;
+  readonly shaderHash: string;
+  readonly disabled: FogPixel;
+  readonly enabled: FogPixel;
+  readonly expected: FogPixel;
+  readonly delta: FogPixel;
+  readonly alphaPreserved: boolean;
+  readonly verdict: 'pass' | 'fail';
+};
+
+const FOG_COLOR = [0.6, 0.45, 0.8] as const;
+const FOG_DENSITY = 0.08;
+const FOG_HEIGHT_FALLOFF = 0.1;
+const FOG_MAX_OPACITY = 0.9;
+const CHANNEL_TOLERANCE = 0.03;
+
+const MATERIAL_IDENTIFIERS: Readonly<Record<string, string>> = {
+  'default-standard-pbr.wgsl': 'forgeax::default-standard-pbr',
+  'default-standard-pbr-skin.wgsl': 'forgeax::pbr-skin',
+  'unlit.wgsl': 'forgeax::default-unlit',
+  'sprite.wgsl': 'forgeax::sprite',
+  'msdf-text.wgsl': 'forgeax::msdf-text',
+  'vfx-render/beam.wgsl': 'forgeax::vfx-render.particles.beam',
+  'vfx-render/billboard.wgsl': 'forgeax::vfx-render.particles.billboard',
+  'vfx-render/mesh.wgsl': 'forgeax::vfx-render.particles.mesh',
+  'vfx-render/ribbon.wgsl': 'forgeax::vfx-render.particles.ribbon',
+  'vfx-render/trail.wgsl': 'forgeax::vfx-render.particles.trail',
+};
+
+function shaderSourceForProducer(
+  producer: FogProducerCase,
+  manifest: FogProbeManifest,
+): { readonly identifier: string; readonly hash: string; readonly source: string } {
+  if (producer.id === 'hdrp-deferred') {
+    const entry = manifest.entries.find((candidate) => candidate.wgsl?.includes('fn fs_lighting'));
+    if (entry?.wgsl === undefined || entry.hash === undefined) {
+      throw new Error(
+        'Fog producer manifest does not contain composed hdrp-deferred-lighting.wgsl',
+      );
+    }
+    return { identifier: 'forgeax::hdrp-deferred-lighting', hash: entry.hash, source: entry.wgsl };
+  }
+  if (producer.sourceFile === 'skybox.wgsl') {
+    const entry = manifest.entries.find((candidate) => candidate.wgsl?.includes('fn skybox_fs'));
+    if (entry?.wgsl === undefined || entry.hash === undefined) {
+      throw new Error('Fog producer manifest does not contain composed skybox.wgsl');
+    }
+    return { identifier: 'forgeax::skybox', hash: entry.hash, source: entry.wgsl };
+  }
+  const identifier = MATERIAL_IDENTIFIERS[producer.sourceFile];
+  if (identifier === undefined)
+    throw new Error(`Fog producer has no shader identifier: ${producer.sourceFile}`);
+  const material = manifest.materialShaders.find(
+    (candidate) => candidate.identifier === identifier,
+  );
+  if (material === undefined)
+    throw new Error(`Fog producer shader is missing from manifest: ${identifier}`);
+  const source = material.composedWgsl;
+  if (source.startsWith('./')) {
+    throw new Error(`Fog producer manifest needs resolved composed WGSL: ${identifier}`);
+  }
+  if (!source.includes(`fn ${producer.entryPoint}`)) {
+    throw new Error(
+      `Fog producer ${producer.id} is missing the owning entry point ${producer.entryPoint}`,
+    );
+  }
+  if (!source.includes('apply_fog')) {
+    throw new Error(`Fog producer ${producer.id} is missing the shared apply_fog call`);
+  }
+  const entry = manifest.entries.find((candidate) => candidate.wgsl === source);
+  return { identifier, hash: entry?.hash ?? identifier, source };
+}
+
+function fogColor(params: {
+  readonly density: number;
+  readonly heightFalloff: number;
+  readonly maxOpacity: number;
+  readonly ray: FogRaySample;
+}): number {
+  const rho0 = params.density * Math.exp(-params.heightFalloff * params.ray.origin[1]);
+  const q = params.heightFalloff * params.ray.direction[1];
+  const tau =
+    Math.abs(q) < 1e-6
+      ? rho0 * params.ray.distance
+      : (rho0 * (1 - Math.exp(-q * params.ray.distance))) / q;
+  return params.maxOpacity * (1 - Math.exp(-Math.max(tau, 0)));
+}
+
+function srgbToLinear(value: number): number {
+  return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+
+function linearToSrgb(value: number): number {
+  const clamped = Math.min(Math.max(value, 0), 1);
+  return clamped <= 0.0031308 ? clamped * 12.92 : 1.055 * clamped ** (1 / 2.4) - 0.055;
+}
+
+function expectedEnabled(
+  producer: FogProducerCase,
+  disabled: FogPixel,
+  ray: FogRaySample,
+): FogPixel {
+  const opacity = fogColor({
+    density: FOG_DENSITY,
+    heightFalloff: FOG_HEIGHT_FALLOFF,
+    maxOpacity: FOG_MAX_OPACITY,
+    ray,
+  });
+  if (producer.domain === 'sprite') {
+    // Native URP frames route the sprite pass to fs_main_hdr when its
+    // transparent attachment is the graph-owned rgba16float target. The
+    // observation is therefore linear premultiplied RGB, not the LDR entry's
+    // sRGB-encoded premultiplied RGB.
+    const alpha = Math.max(disabled[3], 1e-6);
+    const source: readonly [number, number, number] = [
+      disabled[0] / alpha,
+      disabled[1] / alpha,
+      disabled[2] / alpha,
+    ];
+    return [
+      (source[0] * (1 - opacity) + FOG_COLOR[0] * opacity) * alpha,
+      (source[1] * (1 - opacity) + FOG_COLOR[1] * opacity) * alpha,
+      (source[2] * (1 - opacity) + FOG_COLOR[2] * opacity) * alpha,
+      disabled[3],
+    ];
+  }
+  if (producer.domain === 'text') {
+    const alpha = Math.max(disabled[3], 1e-6);
+    const source: readonly [number, number, number] = [
+      srgbToLinear(disabled[0]) / alpha,
+      srgbToLinear(disabled[1]) / alpha,
+      srgbToLinear(disabled[2]) / alpha,
+    ];
+    return [
+      linearToSrgb((source[0] * (1 - opacity) + FOG_COLOR[0] * opacity) * alpha),
+      linearToSrgb((source[1] * (1 - opacity) + FOG_COLOR[1] * opacity) * alpha),
+      linearToSrgb((source[2] * (1 - opacity) + FOG_COLOR[2] * opacity) * alpha),
+      disabled[3],
+    ];
+  }
+  return [
+    disabled[0] * (1 - opacity) + FOG_COLOR[0] * opacity,
+    disabled[1] * (1 - opacity) + FOG_COLOR[1] * opacity,
+    disabled[2] * (1 - opacity) + FOG_COLOR[2] * opacity,
+    disabled[3],
+  ];
+}
+
+export async function runFogProducerPixelProbe(
+  producers: readonly FogProducerCase[],
+  manifest: FogProbeManifest,
+  capture: FogProducerPixelCapture,
+): Promise<readonly FogProducerPixelEvidence[]> {
+  const rows: FogProducerPixelEvidence[] = [];
+  for (const producer of producers) {
+    const shader = shaderSourceForProducer(producer, manifest);
+    const result = await capture(producer);
+    const expected = expectedEnabled(producer, result.disabled, result.ray);
+    const delta: FogPixel = [
+      Math.abs(result.enabled[0] - expected[0]),
+      Math.abs(result.enabled[1] - expected[1]),
+      Math.abs(result.enabled[2] - expected[2]),
+      Math.abs(result.enabled[3] - expected[3]),
+    ];
+    const alphaPreserved = Math.abs(result.enabled[3] - result.disabled[3]) <= CHANNEL_TOLERANCE;
+    const activeSignal = Math.max(
+      Math.abs(result.enabled[0] - result.disabled[0]),
+      Math.abs(result.enabled[1] - result.disabled[1]),
+      Math.abs(result.enabled[2] - result.disabled[2]),
+    );
+    const verdict =
+      Math.max(...delta) <= CHANNEL_TOLERANCE && alphaPreserved && activeSignal > 0.01
+        ? 'pass'
+        : 'fail';
+    rows.push({
+      producerId: producer.id,
+      shaderIdentifier: shader.identifier,
+      shaderHash: shader.hash,
+      disabled: result.disabled,
+      enabled: result.enabled,
+      expected,
+      delta,
+      alphaPreserved,
+      verdict,
+    });
+  }
+  return rows;
+}
+
+export async function loadBrowserFogProbeManifest(): Promise<FogProbeManifest> {
+  const response = await fetch('/shaders/manifest.json');
+  if (!response.ok) throw new Error(`Fog Browser shader manifest unavailable: ${response.status}`);
+  const payload = (await response.json()) as FogProbeManifest;
+  const materialShaders: MaterialManifestEntry[] = [];
+  for (const material of payload.materialShaders) {
+    const resolveSource = async (value: string): Promise<string> => {
+      if (!value.startsWith('./')) return value;
+      const sourceResponse = await fetch(`/shaders/${value.slice(2)}`);
+      if (!sourceResponse.ok) throw new Error(`Fog Browser composed shader unavailable: ${value}`);
+      return sourceResponse.text();
+    };
+    materialShaders.push({
+      identifier: material.identifier,
+      composedWgsl: await resolveSource(material.composedWgsl),
+      ...(material.variants === undefined
+        ? {}
+        : {
+            variants: await Promise.all(
+              material.variants.map(async (variant) => ({
+                composedWgsl: await resolveSource(variant.composedWgsl),
+              })),
+            ),
+          }),
+    });
+  }
+  const entries = await Promise.all(
+    payload.entries.map(async (entry) => ({
+      ...(entry.hash === undefined ? {} : { hash: entry.hash }),
+      ...(entry.wgsl === undefined
+        ? {}
+        : {
+            wgsl: !entry.wgsl.startsWith('./')
+              ? entry.wgsl
+              : await (await fetch(`/shaders/${entry.wgsl.slice(2)}`)).text(),
+          }),
+    })),
+  );
+  return { entries, materialShaders };
+}