@forgeax/engine-runtime 0.1.7 → 0.1.19

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

@@ -120,6 +120,7 @@ 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 { standardMaterialShaderVariants } from './helpers/standard-material-manifest';
 import { drawWithOwners } from './renderer-test-utils';
 
 function componentFieldType(component: { fields: Record<string, { type: string }> }, name: string) {
@@ -1645,7 +1646,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',
@@ -2359,10 +2361,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 +2384,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 +2404,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 +2422,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 +2521,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 +2534,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 +2547,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 +2760,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 +2822,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 +2988,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 +3018,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))}`;
   }
@@ -7292,7 +7306,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 +7623,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 +8709,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/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/renderer-host.ts

@@ -4,7 +4,10 @@ import type {
   BundlerOptions,
   RendererHostAssembly,
 } from '@forgeax/engine-render/internal/construct-renderer';
-import { constructRendererHost } from '@forgeax/engine-render/internal/construct-renderer';
+import {
+  constructRendererHost,
+  EngineEnvironmentError,
+} from '@forgeax/engine-render/internal/construct-renderer';
 import { loadBackendPack } from './backend-selection';
 
 export type {
@@ -12,16 +15,40 @@ export type {
   RendererHostAssembly,
 } from '@forgeax/engine-render/internal/construct-renderer';
 
+const FALLBACK_ERROR_CODES = new Set([
+  'adapter-unavailable',
+  'request-adapter-threw',
+  'feature-not-enabled',
+  'limit-exceeded',
+  'rhi-not-available',
+  'device-lost',
+  'oom',
+]);
+
+function canFallbackToWgpu(error: unknown): boolean {
+  if (!(error instanceof EngineEnvironmentError)) return false;
+  const webgpuError = error.detail.webgpuError;
+  if (webgpuError === undefined || typeof webgpuError !== 'object') return false;
+  if (!('code' in webgpuError)) return false;
+  const code = webgpuError.code;
+  return typeof code === 'string' && FALLBACK_ERROR_CODES.has(code);
+}
+
 /** Assemble renderer plus asset services in the Runtime-owned backend host. */
 export async function constructRuntimeRendererHost(
   canvas: unknown,
   options?: RendererOptions,
   bundler?: BundlerOptions,
-): Promise<RenderResult<RendererHostAssembly, RenderError>> {
+): Promise<RenderResult<RendererHostAssembly, RenderError | EngineEnvironmentError>> {
   const first = await loadBackendPack(options);
   if (!first.ok) throw first.error;
   const constructed = await constructRendererHost(canvas, options, bundler, first.value);
-  if (constructed.ok || options?.rhi !== undefined || typeof globalThis === 'undefined') {
+  if (
+    constructed.ok ||
+    options?.rhi !== undefined ||
+    typeof globalThis === 'undefined' ||
+    !canFallbackToWgpu(constructed.error)
+  ) {
     return constructed;
   }
   const fallback = await loadBackendPack(options, true);