@forgeax/engine-runtime 0.1.6 → 0.1.19

package/src/__tests__/sprite-lit-bgl-byte-identical.test.ts

@@ -47,7 +47,7 @@ function makeSpec(shaderId: string): PipelineSpec {
 
 describe('sprite-lit BGL byte-identical to sprite (AC-07, w4/w5 close)', () => {
   describe('pbr-view BGL (light buffers; binding 1+2)', () => {
-    it('sprite-lit vs sprite share the same 9-entry pbr-view BGL under storage-buffer caps', () => {
+    it('sprite-lit vs sprite share the same 10-entry pbr-view BGL under storage-buffer caps', () => {
       const spriteSpec = makeSpec('forgeax::sprite');
       const spriteLitSpec = makeSpec('forgeax::sprite-lit');
       const sprite = buildBindGroupLayoutDescriptor(spriteSpec, {
@@ -59,10 +59,10 @@ describe('sprite-lit BGL byte-identical to sprite (AC-07, w4/w5 close)', () => {
         caps: { storageBuffer: true },
       });
       expect(JSON.stringify(spriteLit)).toBe(JSON.stringify(sprite));
-      expect(spriteLit.entries.length).toBe(9); // feat-20260625 spot shadow added binding 8 → view BGL grew 8→9
+      expect(spriteLit.entries.length).toBe(10); // binding 10 is the shared Points/Lines view UBO
     });
 
-    it('sprite-lit vs sprite share the same 9-entry pbr-view BGL under uniform fallback caps (AC-10)', () => {
+    it('sprite-lit vs sprite share the same 10-entry pbr-view BGL under uniform fallback caps (AC-10)', () => {
       const spriteSpec = makeSpec('forgeax::sprite');
       const spriteLitSpec = makeSpec('forgeax::sprite-lit');
       const sprite = buildBindGroupLayoutDescriptor(spriteSpec, {
@@ -118,24 +118,24 @@ describe('sprite-lit BGL byte-identical to sprite (AC-07, w4/w5 close)', () => {
   });
 
   describe('material BGL congruence (pbr-material-merged / unlit-material)', () => {
-    it('pbr-material-user-region entries are 13 (PBR layout reused by sprite & sprite-lit)', () => {
+    it('pbr-material-user-region entries are 17 (PBR layout reused by sprite & sprite-lit)', () => {
       // sprite + sprite-lit use the default standard-PBR user-region
-      // schema (5 user fields produce 7 BGL entries after std140 merge).
+      // schema (20 value fields + 8 texture fields produce 17 BGL entries).
       // Both share the same userRegion shape and therefore the same BGL.
       const base = buildPbrMaterialUserRegionEntries();
-      expect(base.length).toBe(13);
+      expect(base.length).toBe(17);
     });
 
-    it('pbr-material-merged stays 24 entries (sprite/sprite-lit do not change material BGL shape)', () => {
+    it('pbr-material-merged stays 26 entries (sprite/sprite-lit do not change material BGL shape)', () => {
       const merged = buildBindGroupLayoutDescriptor(makeSpec('forgeax::sprite-lit'), {
         kind: 'pbr-material-merged',
       });
-      expect(merged.entries.length).toBe(24);
-      // mergeSkylightIntoMaterialBgl + lightmap injection must stay
+      expect(merged.entries.length).toBe(26);
+      // mergeSkylightIntoMaterialBgl + transmission injection must stay
       // append-only against the 7-entry PBR base.
       const base = buildPbrMaterialUserRegionEntries();
       const afterSky = mergeSkylightIntoMaterialBgl(base);
-      const expected = [...afterSky, ...appendInjection(afterSky, 'lightmap')];
+      const expected = [...afterSky, ...appendInjection(afterSky, 'transmission')];
       expect(merged.entries).toEqual(expected);
     });
   });

package/src/__tests__/ssao-passes.test.ts

@@ -8,6 +8,8 @@
 import { RenderGraph } from '@forgeax/engine-render-graph';
 import type { RhiDevice } from '@forgeax/engine-rhi';
 import { describe, expect, it, vi } from 'vitest';
+import { DeviceScope } from '../../../render/src/device/device-scope';
+import type { BloomPersistentBundle } from '../../../render/src/record/render-context';
 import {
   recordBloomBlurHPass,
   recordBloomBlurVPass,
@@ -680,6 +682,31 @@ function makePostProcessRecordCtx(): {
     queue: { writeBuffer: vi.fn(() => ({ ok: true, value: undefined })) },
   };
   const sampler = { label: 'postprocess-sampler' };
+  const bloomScope = DeviceScope.create(1, 'runtime-ssao-bloom-fixture');
+  const ownBloomHandle = (
+    kind: 'pipeline' | 'binding' | 'post-effect' | 'buffer',
+    label: string,
+  ) => {
+    const handle = { label };
+    bloomScope._adopt(kind, handle, () => undefined);
+    return handle;
+  };
+  const bloomResources = {
+    scope: bloomScope,
+    generation: bloomScope.generation,
+    bloomBrightPipeline: ownBloomHandle('pipeline', 'bloom-bright-pipeline'),
+    bloomBlurHPipeline: ownBloomHandle('pipeline', 'bloom-blur-h-pipeline'),
+    bloomBlurVPipeline: ownBloomHandle('pipeline', 'bloom-blur-v-pipeline'),
+    bloomCompositePipeline: ownBloomHandle('pipeline', 'bloom-composite-pipeline'),
+    bloomBrightBindGroupLayout: ownBloomHandle('binding', 'bloom-bright-bgl'),
+    bloomBlurBindGroupLayout: ownBloomHandle('binding', 'bloom-blur-bgl'),
+    bloomCompositeBindGroupLayout: ownBloomHandle('binding', 'bloom-composite-bgl'),
+    bloomSampler: ownBloomHandle('post-effect', 'bloom-sampler'),
+    bloomBrightParamsBuffer: ownBloomHandle('buffer', 'bloom-bright-params'),
+    bloomBlurHParamsBuffer: ownBloomHandle('buffer', 'bloom-blur-h-params'),
+    bloomBlurVParamsBuffer: ownBloomHandle('buffer', 'bloom-blur-v-params'),
+    bloomCompositeParamsBuffer: ownBloomHandle('buffer', 'bloom-composite-params'),
+  } as unknown as BloomPersistentBundle;
   const ctx = {
     runtime: {
       device: { ...device, caps: { storageBuffer: true } },
@@ -702,23 +729,12 @@ function makePostProcessRecordCtx(): {
         skyboxBindGroupLayout: { label: 'skybox-bgl' },
         skyboxSampler: sampler,
         skyboxRotationBuffer: { label: 'skybox-rotation' },
-        bloomBrightPipeline: { label: 'bloom-bright-pipeline' },
-        bloomBrightBindGroupLayout: { label: 'bloom-bright-bgl' },
-        bloomBrightParamsBuffer: { label: 'bloom-bright-params' },
-        bloomBlurHPipeline: { label: 'bloom-blur-h-pipeline' },
-        bloomBlurVPipeline: { label: 'bloom-blur-v-pipeline' },
-        bloomBlurBindGroupLayout: { label: 'bloom-blur-bgl' },
-        bloomBlurHParamsBuffer: { label: 'bloom-blur-h-params' },
-        bloomBlurVParamsBuffer: { label: 'bloom-blur-v-params' },
-        bloomCompositePipeline: { label: 'bloom-composite-pipeline' },
-        bloomCompositeBindGroupLayout: { label: 'bloom-composite-bgl' },
-        bloomCompositeParamsBuffer: { label: 'bloom-composite-params' },
-        bloomSampler: sampler,
         fxaaPipeline: { label: 'fxaa-pipeline' },
         fxaaBindGroupLayout: { label: 'fxaa-bgl' },
         fxaaSampler: sampler,
       },
     },
+    bloomResources,
     frameState: { postProcessBgCache: new WeakMap() },
     bindGroupCounts: { createBindGroup: 0, keys: [] },
     camera: {
@@ -778,6 +794,10 @@ describe('post-process bindgroup identity cache (issue #670)', () => {
       views.bloomBlurV,
     );
     expect(bindGroupCreates[5]?.entries[0]?.resource.value).toBe(views.cubemap);
+    expect(bindGroupCreates[5]?.entries[2]?.resource.value).toEqual({
+      buffer: ctx.pipelineState.viewUniformBuffer,
+      size: 960,
+    });
 
     recordAll();
     expect(bindGroupCreates).toHaveLength(6);

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/collect-scene-asset.ts

@@ -44,8 +44,8 @@
 //   proven to be a mount entity, components is left undefined (one-time
 //   normalization on first reload; fixed-point from second collect onward).
 
-import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import {
+  builtinMeshGuid,
   resolveAssetHandle,
   SceneCollectAssetGuidUnresolvedError,
   SceneCollectEntityRefOutOfClosureError,
@@ -78,6 +78,11 @@ import type {
 } from '@forgeax/engine-types';
 import { foldMountOverrides } from './scene-utils/mount-override-fold';
 
+/** The collector needs identity lookup, not an authoring registry implementation. */
+export interface SceneAssetGuidLookup {
+  guidOf(asset: Asset): string | undefined;
+}
+
 // Shared helpers
 function _isArrayLike(value: unknown): value is ArrayLike<unknown> {
   // SceneAsset values are ordinary JSON arrays at the boundary. Use the
@@ -116,14 +121,16 @@ function classifyFieldSchema(fieldType: string | undefined): SchemaFieldClass |
 // lives in exactly one place; `field` names the failing field in the error.
 function _handleToGuid(
   world: World,
-  registry: AssetRegistry,
+  registry: SceneAssetGuidLookup,
   handle: number,
   field: string,
 ): Result<string | undefined, SceneCollectAssetGuidUnresolvedError> {
   if (handle === 0) return ok(undefined); // NULL sentinel
+  const builtinGuid = builtinMeshGuid(handle as unknown as Handle<string, 'shared'>);
+  if (builtinGuid !== undefined) return ok(builtinGuid);
   const assetRes = resolveAssetHandle(world, handle as unknown as Handle<string, 'shared'>);
   if (!assetRes.ok) return err(new SceneCollectAssetGuidUnresolvedError(field, handle));
-  const guid = registry._guidForAsset(assetRes.value as Asset);
+  const guid = registry.guidOf(assetRes.value as Asset);
   if (guid === undefined) return err(new SceneCollectAssetGuidUnresolvedError(field, handle));
   return ok(guid);
 }
@@ -135,7 +142,7 @@ function _handleToGuid(
 // values pass through untouched.
 function _serializeSharedFieldValue(
   world: World,
-  registry: AssetRegistry,
+  registry: SceneAssetGuidLookup,
   classification: SchemaFieldClass,
   value: unknown,
   field: string,
@@ -166,7 +173,7 @@ function _serializeSharedFieldValue(
 // override IS that field so it cannot be omitted). Non-shared fields pass through.
 function _serializeOverrideValueHandles(
   world: World,
-  registry: AssetRegistry,
+  registry: SceneAssetGuidLookup,
   ov: MountOverride,
 ): Result<unknown, SceneCollectAssetGuidUnresolvedError> {
   const comp = world.components.resolve(ov.comp);
@@ -253,7 +260,7 @@ export function serializeSceneAssetToPack(
  * filter (not subtree pruning): graft entities under members survive as owned.
  */
 export function rootsToSceneAsset(
-  registry: AssetRegistry,
+  registry: SceneAssetGuidLookup,
   world: World,
   roots: EntityHandle[],
 ): Result<
@@ -415,7 +422,7 @@ export function rootsToSceneAsset(
           sh.value as unknown as number,
         ),
       );
-    const g = registry._guidForAsset(pr.value as Asset);
+    const g = registry.guidOf(pr.value as Asset);
     if (g === undefined)
       return err(
         new SceneCollectAssetGuidUnresolvedError(

package/src/index.ts

@@ -326,7 +326,11 @@ export { quat } from '@forgeax/engine-math';
 // collectSceneAsset removed — replaced by rootsToSceneAsset (forest entry,
 // schema-derived field dispatch, engine-self-contained GUID resolution).
 // serializeSceneAssetToPack now uses schema-derived refs[] index (D-1/D-2).
-export { rootsToSceneAsset, serializeSceneAssetToPack } from './collect-scene-asset';
+export {
+  rootsToSceneAsset,
+  type SceneAssetGuidLookup,
+  serializeSceneAssetToPack,
+} from './collect-scene-asset';
 // feat-20260626 M6 / m6-4: debug-draw auto-attach glue is re-exported from the
 // main barrel (was a separate tsup entry). The separate entry produced a SECOND
 // module copy of the mutable `registeredDebugDraw` registry: createApp set it on

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);