@forgeax/engine-runtime 0.1.7 → 0.1.20

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

@@ -120,6 +120,8 @@ import { INSTANCE_STORAGE_STRIDE_FLOATS } from '../../../render/src/record/mesh-
 import { selectSwapChainFormat } from '../../../render/src/render-system';
 import { createSkinPaletteAllocator } from '../../../render/src/systems/skin-palette-allocator';
 import type { TransparentEntry } from '../../../render/src/systems/transparent-sort-config';
+import { createTemporalFrameTransaction } from '../../../render/src/temporal/frame';
+import { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 import { drawWithOwners } from './renderer-test-utils';
 
 function componentFieldType(component: { fields: Record<string, { type: string }> }, name: string) {
@@ -761,6 +763,8 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         [],
         {
           frameNumber: 0,
+          temporalFrameTransaction: createTemporalFrameTransaction({ deviceEpoch: 0 }),
+          temporalFrameInput: undefined,
           compiledFrameGraph: null,
           compiledFrameGraphTopologyKey: null,
           retiredCompiledFrameGraphs: new Set(),
@@ -816,6 +820,8 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         [],
         {
           frameNumber: 0,
+          temporalFrameTransaction: createTemporalFrameTransaction({ deviceEpoch: 0 }),
+          temporalFrameInput: undefined,
           compiledFrameGraph: null,
           compiledFrameGraphTopologyKey: null,
           retiredCompiledFrameGraphs: new Set(),
@@ -1645,7 +1651,8 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       sourcePath: `${identifier}.wgsl`,
       composedWgsl,
       paramSchema: '[]',
-      variants: [],
+      variants:
+        identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
     });
     const manifest = {
       schemaVersion: '1.0.0',
@@ -2079,8 +2086,10 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       );
     });
 
-    it('imports View from forgeax_view::common', () => {
-      expect(source).toEqual(expect.stringContaining('#import forgeax_view::common::{View'));
+    it('imports View from forgeax_view::common as the sole view ABI', () => {
+      expect(source).toEqual(expect.stringContaining('#import forgeax_view::common::View'));
+      expect(source).not.toContain('FogRay');
+      expect(source).not.toContain('fogRayFromNdc');
     });
 
     it('imports fullscreen_triangle from forgeax_view::common', () => {
@@ -2359,10 +2368,10 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
     });
   });
 
-  // ─── Assertion (d): assembleMaterialWithSkylightEntries merges 7 + 7 = 14 ───
+  // ─── Assertion (d): assembleMaterialWithSkylightEntries adds the engine-owned pair ───
 
   describe('t40 round-4 (d) assembleMaterialWithSkylightEntries shape', () => {
-    it('returns 14 BindGroupEntry values; entry 7..13 reference the skylight resources', () => {
+    it('returns 16 BindGroupEntry values; entry 7..13 reference the skylight resources', () => {
       const materialEntries = makeMaterialBindGroupEntries();
       const irrView = { __brand: 'TextureView', id: 1 } as unknown as TextureView;
       const irrSampler = { __brand: 'Sampler', id: 1 } as unknown as Sampler;
@@ -2382,7 +2391,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         intensityBuffer: intensityBuf,
       });
 
-      expect(merged).toHaveLength(14);
+      expect(merged).toHaveLength(16);
 
       // Skylight entries at binding 7..13 in D-5 order
       expect(merged[7]?.binding).toBe(7);
@@ -2402,6 +2411,8 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         kind: 'buffer',
         value: { buffer: intensityBuf },
       });
+      expect(merged[14]?.binding).toBe(14);
+      expect(merged[15]?.binding).toBe(15);
     });
 
     it('derives IBL injection start from materialEntries.length (per-shader user-region, not a fixed 7)', () => {
@@ -2418,9 +2429,11 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         brdfLutSampler: {} as Sampler,
         intensityBuffer: {} as Buffer,
       });
-      expect(merged).toHaveLength(7);
+      expect(merged).toHaveLength(9);
       expect(merged[0]?.binding).toBe(0);
       expect(merged[6]?.binding).toBe(6);
+      expect(merged[7]?.binding).toBe(7);
+      expect(merged[8]?.binding).toBe(8);
     });
   });
 }
@@ -2515,7 +2528,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
   }
 
   describe('t58 (M4 round-4) -- material BG fallback path', () => {
-    it('(a) assemble with fallback returns 14 entries; binding 7..13 reference fallback resources', () => {
+    it('(a) assemble with fallback returns 16 entries; binding 7..13 reference fallback resources', () => {
       const materialEntries = makeMaterialBindGroupEntries();
       const fallback = makeFallback();
       const fallbackAsActive: SkylightBindGroupResources = {
@@ -2528,7 +2541,7 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         intensityBuffer: fallback.intensityBuffer,
       };
       const merged = assembleMaterialWithSkylightEntries(materialEntries, fallbackAsActive);
-      expect(merged).toHaveLength(14);
+      expect(merged).toHaveLength(16);
       expect(merged[7]?.binding).toBe(7);
       expect((merged[7]?.resource as { value: unknown }).value).toBe(fallback.irradianceView);
       expect((merged[8]?.resource as { value: unknown }).value).toBe(fallback.sampler);
@@ -2541,11 +2554,11 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       );
     });
 
-    it('(b) assemble with active returns 14 entries; binding 7..13 reference active IblPipelineCache resources', () => {
+    it('(b) assemble with active returns 16 entries; binding 7..13 reference active IblPipelineCache resources', () => {
       const materialEntries = makeMaterialBindGroupEntries();
       const active = makeActive();
       const merged = assembleMaterialWithSkylightEntries(materialEntries, active);
-      expect(merged).toHaveLength(14);
+      expect(merged).toHaveLength(16);
       expect((merged[7]?.resource as { value: unknown }).value).toBe(active.irradianceView);
       expect((merged[8]?.resource as { value: unknown }).value).toBe(active.irradianceSampler);
       expect((merged[9]?.resource as { value: unknown }).value).toBe(active.prefilterView);
@@ -2754,47 +2767,43 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       expect(layout?.label).toBe('pbr-pl');
     });
 
-    it('(b) PBR material BGL entry count === 24 (user region 0..12 + Skylight 13..19 + lightmap 20..23)', () => {
+    it('(b) PBR material BGL entry count === 26 (user region 0..16 + Skylight 17..23 + transmission 24..25)', () => {
       const device = makeMockDevice();
       // biome-ignore lint/suspicious/noExplicitAny: structural mock
       buildPbrPipelineLayouts(device as any, STORAGE_CAPS);
       const materialBgl = device.capturedBgls.find((b) => b.label === 'pbr-material-skylight-bgl');
       expect(materialBgl).toBeDefined();
-      expect(materialBgl?.entries).toHaveLength(24);
+      expect(materialBgl?.entries).toHaveLength(26);
     });
 
-    it('(c) binding indices 0..23 in order; 13..19 resource types in D-5 round-4 order; 20..23 lightmap', () => {
+    it('(c) binding indices 0..25 in order; 17..23 resource types in D-5 round-4 order; 24..25 transmission', () => {
       const device = makeMockDevice();
       // biome-ignore lint/suspicious/noExplicitAny: structural mock
       buildPbrPipelineLayouts(device as any, STORAGE_CAPS);
       const materialBgl = device.capturedBgls.find((b) => b.label === 'pbr-material-skylight-bgl');
       expect(materialBgl).toBeDefined();
       const entries = materialBgl?.entries ?? [];
-      // binding indices 0..23 in order
-      for (let i = 0; i < 24; i++) {
+      // binding indices 0..25 in order
+      for (let i = 0; i < 26; i++) {
         expect(entries[i]?.binding).toBe(i);
       }
-      // 13..19 resource types
-      expect((entries[13] as { texture?: { viewDimension: string } }).texture?.viewDimension).toBe(
+      // 17..23 resource types
+      expect((entries[17] as { texture?: { viewDimension: string } }).texture?.viewDimension).toBe(
         'cube',
       );
-      expect((entries[14] as { sampler?: { type: string } }).sampler?.type).toBe('filtering');
-      expect((entries[15] as { texture?: { viewDimension: string } }).texture?.viewDimension).toBe(
+      expect((entries[18] as { sampler?: { type: string } }).sampler?.type).toBe('filtering');
+      expect((entries[19] as { texture?: { viewDimension: string } }).texture?.viewDimension).toBe(
         'cube',
       );
-      expect((entries[16] as { sampler?: { type: string } }).sampler?.type).toBe('filtering');
-      expect((entries[17] as { texture?: { viewDimension: string } }).texture?.viewDimension).toBe(
-        '2d',
-      );
-      expect((entries[18] as { sampler?: { type: string } }).sampler?.type).toBe('filtering');
-      expect((entries[19] as { buffer?: { type: string } }).buffer?.type).toBe('uniform');
-      // 20..23 lightmap resource types
       expect((entries[20] as { sampler?: { type: string } }).sampler?.type).toBe('filtering');
       expect((entries[21] as { texture?: { viewDimension: string } }).texture?.viewDimension).toBe(
         '2d',
       );
       expect((entries[22] as { sampler?: { type: string } }).sampler?.type).toBe('filtering');
-      expect((entries[23] as { texture?: { viewDimension: string } }).texture?.viewDimension).toBe(
+      expect((entries[23] as { buffer?: { type: string } }).buffer?.type).toBe('uniform');
+      // 24..25 transmission resource types
+      expect((entries[24] as { sampler?: { type: string } }).sampler?.type).toBe('filtering');
+      expect((entries[25] as { texture?: { viewDimension: string } }).texture?.viewDimension).toBe(
         '2d',
       );
     });
@@ -2820,13 +2829,13 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
   // ─── (e)(f) Unlit material BGL shape + name ─────────────────────────────────
 
   describe('t57 (M4 round-4) -- unlitPipeline material BGL shape', () => {
-    it('(e) unlit material BGL entry count === 13 (no Skylight binding contamination)', () => {
+    it('(e) unlit material BGL entry count === 17 (no Skylight binding contamination)', () => {
       const device = makeMockDevice();
       // biome-ignore lint/suspicious/noExplicitAny: structural mock
       buildUnlitMaterialBgl(device as any);
       const unlitBgl = device.capturedBgls.find((b) => b.label === 'unlit-material-bgl');
       expect(unlitBgl).toBeDefined();
-      expect(unlitBgl?.entries).toHaveLength(13);
+      expect(unlitBgl?.entries).toHaveLength(17);
     });
 
     it("(f) PBR material BGL labelled 'pbr-material-skylight-bgl'; unlit labelled 'unlit-material-bgl'", () => {
@@ -2986,6 +2995,14 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
   }
 
   function buildManifestDataUrl(): string {
+    const materialShaderStub = (identifier: string) => ({
+      identifier,
+      sourcePath: `${identifier}.wgsl`,
+      composedWgsl: '/* stub */',
+      paramSchema: '[]',
+      variants:
+        identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
+    });
     const manifest = {
       schemaVersion: '1.0.0',
       entries: [
@@ -3008,6 +3025,10 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
           bindings: '',
         },
       ],
+      materialShaders: [
+        materialShaderStub('forgeax::default-standard-pbr'),
+        materialShaderStub('forgeax::default-unlit'),
+      ],
     };
     return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
   }
@@ -3436,6 +3457,8 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         [],
         {
           frameNumber: 0,
+          temporalFrameTransaction: createTemporalFrameTransaction({ deviceEpoch: 0 }),
+          temporalFrameInput: undefined,
           compiledFrameGraph: null,
           compiledFrameGraphTopologyKey: null,
           retiredCompiledFrameGraphs: new Set(),
@@ -3555,6 +3578,8 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         [],
         {
           frameNumber: 0,
+          temporalFrameTransaction: createTemporalFrameTransaction({ deviceEpoch: 0 }),
+          temporalFrameInput: undefined,
           compiledFrameGraph: null,
           compiledFrameGraphTopologyKey: null,
           retiredCompiledFrameGraphs: new Set(),
@@ -3628,6 +3653,8 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
         [],
         {
           frameNumber: 0,
+          temporalFrameTransaction: createTemporalFrameTransaction({ deviceEpoch: 0 }),
+          temporalFrameInput: undefined,
           compiledFrameGraph: null,
           compiledFrameGraphTopologyKey: null,
           retiredCompiledFrameGraphs: new Set(),
@@ -7292,7 +7319,8 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       sourcePath: `${identifier}.wgsl`,
       composedWgsl,
       paramSchema: '[]',
-      variants: [],
+      variants:
+        identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
     });
     const manifest = {
       schemaVersion: '1.0.0',
@@ -7608,7 +7636,8 @@ import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
       sourcePath: `${identifier}.wgsl`,
       composedWgsl: '/* stub */',
       paramSchema: '[]',
-      variants: [],
+      variants:
+        identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
     });
     const manifest = {
       schemaVersion: '1.0.0',
@@ -8693,7 +8722,8 @@ type ExtractFramesWithPipeline = (
       sourcePath: `${identifier}.wgsl`,
       composedWgsl: '/* stub */',
       paramSchema: '[]',
-      variants: [],
+      variants:
+        identifier === 'forgeax::default-standard-pbr' ? standardMaterialShaderVariants() : [],
     });
     const entries: Array<{ hash: string; wgsl: string; glsl: string; bindings: string }> = [
       { hash: 'pbr00000', wgsl: '/* pbr stub - calls f_schlick( */', glsl: '', bindings: '' },

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

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

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

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

package/src/__tests__/volumetric-fog-record-recovery.integration.test.ts

@@ -0,0 +1,180 @@
+// @perf-budget-skip: intentional full Renderer submit-failure and LKG recovery integration gate.
+import { World } from '@forgeax/engine-ecs';
+import {
+  Camera,
+  DirectionalLight,
+  perspective,
+  TONEMAP_ACES_FILMIC,
+  VolumetricFog,
+} from '@forgeax/engine-render';
+import type { CommandBuffer, RhiQueue } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import { rhi as nullRhi, RhiNullAdapter } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { err, type Result, type TextureAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from '../createRenderer';
+
+const VOLUME_MANIFEST = `data:application/json,${encodeURIComponent(
+  JSON.stringify({
+    entries: [
+      { hash: 'pbr', wgsl: 'f_schlick', glsl: '', bindings: '' },
+      { hash: 'unlit', wgsl: 'unlit', glsl: '', bindings: '' },
+      { hash: 'tonemap', wgsl: 'struct TonemapParams {}', glsl: '', bindings: '' },
+      { hash: 'volume-inject', wgsl: 'fn volume_inject() {}', glsl: '', bindings: '' },
+      { hash: 'volume-integrate', wgsl: 'fn volume_integrate() {}', glsl: '', bindings: '' },
+      { hash: 'volume-temporal', wgsl: 'fn volume_temporal() {}', glsl: '', bindings: '' },
+      { hash: 'volume-composite', wgsl: 'fn volume_fs() {}', glsl: '', bindings: '' },
+    ],
+  }),
+)}`;
+
+function canvas(): HTMLCanvasElement {
+  return { width: 64, height: 64, getContext: () => null } as unknown as HTMLCanvasElement;
+}
+
+function density(): TextureAsset {
+  return {
+    kind: 'texture',
+    shape: { viewDimension: '3d', extent: { width: 64, height: 64, depth: 64 } },
+    format: 'r8unorm',
+    colorSpace: 'linear',
+    mips: { kind: 'none' },
+    data: new Uint8Array(64 * 64 * 64).fill(32),
+  };
+}
+
+function failingNullRhi(controller: { failNext: boolean }) {
+  const adapter = new RhiNullAdapter();
+  const requestDevice = adapter.requestDevice.bind(adapter);
+  adapter.requestDevice = async (options) => {
+    const result = await requestDevice(options);
+    if (!result.ok) return result;
+    const queue: RhiQueue = result.value.queue;
+    const submit = queue.submit.bind(queue);
+    queue.submit = (buffers: readonly CommandBuffer[]): Result<void, RhiError> => {
+      if (controller.failNext) {
+        controller.failNext = false;
+        return err(
+          new RhiError({
+            code: 'webgpu-runtime-error',
+            expected: 'queue submission to succeed',
+            hint: 'the recovery regression intentionally rejects one submit',
+          }),
+        );
+      }
+      return submit(buffers);
+    };
+    return result;
+  };
+  return {
+    ...nullRhi,
+    requestAdapter: async () => ({ ok: true, value: adapter }),
+  };
+}
+
+describe('volumetric fog record recovery projection', () => {
+  it('keeps accepted LKG inspection on a failed submit and clears it after repair', async () => {
+    const controller = { failNext: false };
+    const created = await createRenderer(
+      canvas(),
+      { rhi: failingNullRhi(controller) as never },
+      { shaderManifestUrl: VOLUME_MANIFEST },
+    );
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const renderer = created.value;
+
+    const world = new World();
+    const densityHandle = world.allocSharedRef('TextureAsset', density());
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 3] } },
+        {
+          component: Camera,
+          data: {
+            ...perspective({ fov: Math.PI / 4, aspect: 1 }),
+            tonemap: TONEMAP_ACES_FILMIC,
+          },
+        },
+      )
+      .unwrap();
+    const directionalLight = world
+      .spawn({
+        component: DirectionalLight,
+        data: { direction: [-0.4, -0.8, -0.3], castShadow: true },
+      })
+      .unwrap();
+    const fogEntity = world
+      .spawn({
+        component: VolumetricFog,
+        data: {
+          light: directionalLight,
+          density: densityHandle,
+          boundsMin: [-1, -1, -1],
+          boundsMax: [1, 1, 1],
+          extinction: [0.2, 0.2, 0.2],
+          albedo: [0.8, 0.8, 0.8],
+          emission: [0, 0, 0],
+          anisotropy: 0,
+          maxDistance: 50,
+        },
+      })
+      .unwrap();
+    expect(world.update(1 / 60).ok).toBe(true);
+
+    const lease = renderer.attach(world);
+    expect(lease.ok).toBe(true);
+    if (!lease.ok) return;
+    const request = {
+      leases: [lease.value],
+      camera: { lease: lease.value },
+      environment: { lease: lease.value },
+    } as const;
+
+    expect(renderer.draw(request).ok).toBe(true);
+    expect(renderer.inspect().volumetricFog).toMatchObject({
+      status: 'available',
+      resourceStage: 'accepted',
+      generation: 1,
+      passCount: 4,
+    });
+
+    controller.failNext = true;
+    expect(renderer.draw(request).ok).toBe(false);
+    expect(renderer.inspect().volumetricFog).toMatchObject({
+      status: 'degraded',
+      resourceStage: 'lkg',
+      generation: 1,
+      lkgGeneration: 1,
+      candidateGeneration: 1,
+      candidateFailure: 'submit-failed',
+      passCount: 4,
+      // The packed high profile uses a 64x64x16 physical froxel texture,
+      // representing 64 logical slices per pixel. Inspection reports the
+      // descriptor-derived allocation bytes for this recovery fixture.
+      sampleCount: 64 * 64 * 16,
+      memoryBytes: 71808,
+    });
+
+    expect(renderer.draw(request).ok).toBe(true);
+    expect(renderer.inspect().volumetricFog).toMatchObject({
+      status: 'available',
+      resourceStage: 'accepted',
+      generation: 1,
+      passCount: 4,
+      candidateFailure: undefined,
+    });
+
+    expect(world.removeComponent(fogEntity, VolumetricFog).ok).toBe(true);
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(renderer.draw(request).ok).toBe(true);
+    expect(renderer.inspect().volumetricFog).toMatchObject({
+      status: 'off',
+      passCount: 0,
+      sampleCount: 0,
+      memoryBytes: 0,
+    });
+    expect((await renderer.dispose()).ok).toBe(true);
+  });
+});

package/src/backend-selection.ts

@@ -11,6 +11,9 @@ export function loadRhiPack(
   const createShaderModule = mod.createShaderModule as
     | RhiBackendPack['createShaderModule']
     | undefined;
+  const createShaderModuleImmediate = mod.createShaderModuleImmediate as
+    | RhiBackendPack['createShaderModuleImmediate']
+    | undefined;
   const translateErrorEventToRhiError = mod.translateErrorEventToRhiError as
     | RhiBackendPack['translateErrorEventToRhiError']
     | undefined;
@@ -23,6 +26,7 @@ export function loadRhiPack(
   const pack: RhiBackendPack = {
     rhi,
     ...(createShaderModule === undefined ? {} : { createShaderModule }),
+    ...(createShaderModuleImmediate === undefined ? {} : { createShaderModuleImmediate }),
     ...(translateErrorEventToRhiError === undefined ? {} : { translateErrorEventToRhiError }),
     ...(rawDeviceAccessor === undefined ? {} : { _internal_getRawDevice: rawDeviceAccessor }),
   };

package/src/createRenderer.ts

@@ -30,6 +30,9 @@ export async function createRenderer(
           ...(options.rhi === undefined ? {} : { rhi: options.rhi }),
           ...(options.features === undefined ? {} : { features: options.features }),
           ...(options.profiler === undefined ? {} : { profiler: options.profiler }),
+          ...(options.captureGpuTimings === undefined
+            ? {}
+            : { captureGpuTimings: options.captureGpuTimings }),
           ...(options.rhiInstrumentation === undefined
             ? {}
             : { rhiInstrumentation: options.rhiInstrumentation }),