@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/world-scene-nested.test.ts

@@ -0,0 +1,230 @@
+import * as SceneOwner from '@forgeax/engine-scene';
+// feat-20260608-scene-nesting-ecs-fication M2 / w18 (red phase) — nested /
+// cross-boundary / deep / multi-mount cases.
+//
+// Test file location rationale: same as world-scene-instantiate.test.ts —
+// uses SceneInstance / Transform tokens (defined in @forgeax/engine-runtime),
+// so the test physically lives in runtime; the World methods themselves
+// resolve to @forgeax/engine-ecs.
+//
+// AC anchors:
+//   - AC-23 (double-nested A->B->C: query<SceneInstance>() returns >=3 roots)
+//   - AC-24 (cross-boundary: outer entities[].ChildOf.parent points into a
+//     mount sub-region)
+//   - AC-25 (deep nesting >=5 layers does not stack-overflow)
+//   - AC-26 (same prefab mounted multiple times: mappings disjoint, overrides
+//     do not leak across mount instances)
+
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import { SceneInstance } from '@forgeax/engine-render';
+import { ChildOf } from '@forgeax/engine-scene';
+import type { Handle, SceneAsset } from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { registerSceneComponents } from './helpers/register-scene-components';
+
+function registerSceneAsset(world: World, asset: SceneAsset): Handle<'SceneAsset', 'shared'> {
+  registerSceneComponents(world);
+  return world.allocSharedRef('SceneAsset', asset);
+}
+
+describe('AC-23 double-nested A -> B -> C', () => {
+  it('query<SceneInstance>() returns >=3 SceneInstance roots after instantiating A', () => {
+    const world = new World();
+    // Bottom asset C: 1 entity
+    const assetC: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: {} } }],
+    };
+    const handleC = registerSceneAsset(world, assetC);
+    // Middle asset B: 1 entity + 1 mount of C
+    const assetB: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: {} } }],
+      mounts: [
+        {
+          localId: 1 as never,
+          source: 0,
+          memberFirst: 2 as never,
+          memberCount: 1,
+        },
+      ],
+    };
+    const handleB = registerSceneAsset(world, assetB);
+    // Outer asset A: 1 entity + 1 mount of B
+    const assetA: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: {} } }],
+      mounts: [
+        {
+          localId: 1 as never,
+          source: 0,
+          memberFirst: 2 as never,
+          memberCount: 3,
+        },
+      ],
+    };
+    const handleA = registerSceneAsset(world, assetA);
+
+    // Wire SceneAsset resolver: each mount.source `0` resolves to the
+    // applicable child handle. We use a thread-local trick — the
+    // instantiateScene impl is expected to use a SceneAssetResolver wired
+    // through engine.assets in production; for the unit test we set a
+    // resolver directly by stuffing handles into a Map keyed by parent.
+    // The test relies on World using the same registry the SceneAsset was
+    // alloc'd into; mount.source -> child handle resolution is done by
+    // looking up `parent.refs[source]` in the implementation. Since this
+    // unit test creates raw POD assets in-memory without `refs`, the
+    // implementation must accept an explicit resolver arm — see
+    // _setSceneAssetResolver below.
+    SceneOwner.worldSetSceneAssetResolver(world, (sourceIdx, parentHandle) => {
+      void sourceIdx;
+      const parentManagedRaw = parentHandle as unknown as number;
+      // Parent A handle u32 -> handle B; parent B handle u32 -> handle C.
+      if (parentManagedRaw === (handleA as unknown as number)) return ok(handleB);
+      if (parentManagedRaw === (handleB as unknown as number)) return ok(handleC);
+      return err({ code: 'asset-not-found' });
+    });
+
+    const r = SceneOwner.worldInstantiateScene(world, handleA);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+
+    let count = 0;
+    const query = world.query({ with: [SceneInstance] }).unwrap();
+    for (const _row of query) count += 1;
+    expect(count).toBeGreaterThanOrEqual(3);
+  });
+});
+
+describe('AC-25 deep nesting >=5 layers — no stack overflow', () => {
+  it('5-layer chain instantiates successfully', () => {
+    const world = new World();
+    // Build chain L0 ... L5 where Lk mounts L(k+1).
+    // R2/B-2: mount.memberCount must equal child.totalSlots; recompute
+    // bottom-up. L5 has no mounts -> totalSlots=1; each k<5 has
+    // 1 entity + 1 mount.localId + memberCount(=child.totalSlots) slots.
+    const handles: Handle<'SceneAsset', 'shared'>[] = [];
+    let childTotalSlots = 1; // L5: just one entity
+    for (let k = 5; k >= 0; k -= 1) {
+      const asset: SceneAsset = {
+        kind: 'scene',
+        entities: [{ localId: 0 as never, components: { Transform: {} } }],
+        mounts:
+          k < 5
+            ? [
+                {
+                  localId: 1 as never,
+                  source: 0,
+                  memberFirst: 2 as never,
+                  memberCount: childTotalSlots,
+                },
+              ]
+            : [],
+      };
+      handles.unshift(registerSceneAsset(world, asset));
+      // Update for the parent layer above.
+      // totalSlots = 1 entity + 1 mount.localId + memberCount slots
+      childTotalSlots = k < 5 ? 1 + 1 + childTotalSlots : 1;
+    }
+    SceneOwner.worldSetSceneAssetResolver(world, (sourceIdx, parentHandle) => {
+      void sourceIdx;
+      const raw = parentHandle as unknown as number;
+      for (let k = 0; k < handles.length - 1; k += 1) {
+        if (raw === (handles[k] as unknown as number)) {
+          const next = handles[k + 1];
+          if (next === undefined) break;
+          return ok(next);
+        }
+      }
+      return err({ code: 'asset-not-found' });
+    });
+    const r = SceneOwner.worldInstantiateScene(world, handles[0] as Handle<'SceneAsset', 'shared'>);
+    expect(r.ok).toBe(true);
+  });
+});
+
+describe('AC-26 same prefab mounted multiple times — disjoint mappings', () => {
+  it('two mounts of the same child each get their own member entities', () => {
+    const world = new World();
+    const child: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: { pos: [99, 0, 0] } } }],
+    };
+    const childHandle = registerSceneAsset(world, child);
+    // Parent: 1 entity + 2 mounts of `child`
+    const parent: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: {} } }],
+      mounts: [
+        { localId: 1 as never, source: 0, memberFirst: 3 as never, memberCount: 1 },
+        { localId: 2 as never, source: 0, memberFirst: 4 as never, memberCount: 1 },
+      ],
+    };
+    const parentHandle = registerSceneAsset(world, parent);
+    SceneOwner.worldSetSceneAssetResolver(world, (sourceIdx, parentH) => {
+      void sourceIdx;
+      void parentH;
+      return ok(childHandle);
+    });
+    const r = SceneOwner.worldInstantiateScene(world, parentHandle);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    const inst = world.get(r.value.root, SceneInstance);
+    if (!inst.ok) throw new Error('get SceneInstance failed');
+    expect(inst.value.mapping).toBeInstanceOf(Uint32Array);
+    if (!(inst.value.mapping instanceof Uint32Array)) return;
+    // Two mount-time children at memberFirst=3 and memberFirst=4 should be
+    // distinct entities.
+    const m3 = inst.value.mapping[3];
+    const m4 = inst.value.mapping[4];
+    expect(m3).toBeDefined();
+    expect(m4).toBeDefined();
+    expect(m3).not.toBe(m4);
+  });
+});
+
+describe('AC-24 outer entity ChildOf points into mount sub-region', () => {
+  it('outer entity carries ChildOf with parent=mapping[memberFirst+k]', () => {
+    const world = new World();
+    const child: SceneAsset = {
+      kind: 'scene',
+      entities: [
+        { localId: 0 as never, components: { Transform: {} } },
+        { localId: 1 as never, components: { Transform: {} } },
+      ],
+    };
+    const childHandle = registerSceneAsset(world, child);
+    // Outer scene: entity[0] is independent root; entity[1] declares
+    // ChildOf {parent: 3} — referencing the FIRST member of the mount at
+    // localId=2 (memberFirst=3). The runtime must remap localId=3 to the
+    // live spawned member entity.
+    const parent: SceneAsset = {
+      kind: 'scene',
+      entities: [
+        { localId: 0 as never, components: { Transform: {} } },
+        { localId: 1 as never, components: { Transform: {}, ChildOf: { parent: 3 } } },
+      ],
+      mounts: [{ localId: 2 as never, source: 0, memberFirst: 3 as never, memberCount: 2 }],
+    };
+    const parentHandle = registerSceneAsset(world, parent);
+    SceneOwner.worldSetSceneAssetResolver(world, () => ok(childHandle));
+    const r = SceneOwner.worldInstantiateScene(world, parentHandle);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    const inst = world.get(r.value.root, SceneInstance);
+    if (!inst.ok) throw new Error('get failed');
+    expect(inst.value.mapping).toBeInstanceOf(Uint32Array);
+    if (!(inst.value.mapping instanceof Uint32Array)) return;
+    const outerE = inst.value.mapping[1] as unknown as number;
+    const memberE = inst.value.mapping[3] as unknown as number;
+    const co = world.get(outerE as never, ChildOf);
+    expect(co.ok).toBe(true);
+    if (!co.ok) return;
+    expect(co.value.parent as unknown as number).toBe(memberE);
+  });
+});
+
+// Force-reference defineComponent so a future TS pruning pass keeps the
+// import alive even if all explicit calls are inlined into a deeper helper.
+void defineComponent;

package/src/__tests__/world-scene-override.test.ts

@@ -0,0 +1,199 @@
+import * as SceneOwner from '@forgeax/engine-scene';
+// feat-20260608-scene-nesting-ecs-fication M2 / w20 (red phase) —
+// setSceneOverride / removeSceneOverride / detachSceneMember /
+// reattachSceneMember + AC-19 mount-time override apply invariants.
+//
+// AC anchors:
+//   - AC-19 mount-time override apply: world.get(member, Comp).field ===
+//     overrideValue AND world.get(root, SceneInstance).state.overrides
+//     contains the entry (plan-review F-1 — must assert BOTH the readback
+//     AND the state map population);
+//   - AC-20 setSceneOverride writes the override + readback equals value;
+//     removeSceneOverride rolls back to the source SceneAsset value.
+//   - detach/reattach mark the localId in state.detachedLocalIds; member
+//     entity remains alive.
+//   - setSceneOverride type mismatch -> Err 'scene-override-type-mismatch'
+//     with detail.{ comp, field, expectedType, actualType }.
+
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import { SceneInstance } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import type { Handle, SceneAsset } from '@forgeax/engine-types';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { registerSceneComponents } from './helpers/register-scene-components';
+
+function registerSceneAsset(world: World, asset: SceneAsset): Handle<'SceneAsset', 'shared'> {
+  registerSceneComponents(world);
+  return world.allocSharedRef('SceneAsset', asset);
+}
+
+describe('AC-19 mount-time override apply (w20)', () => {
+  it('mount.overrides land on member entity AND in state.overrides map', () => {
+    const world = new World();
+    const child: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: { pos: [1, 0, 0] } } }],
+    };
+    const childHandle = registerSceneAsset(world, child);
+    const parent: SceneAsset = {
+      kind: 'scene',
+      entities: [],
+      mounts: [
+        {
+          localId: 0 as never,
+          source: 0,
+          memberFirst: 1 as never,
+          memberCount: 1,
+          overrides: [{ localId: 1 as never, comp: 'Transform', field: 'pos', value: [42, 0, 0] }],
+        },
+      ],
+    };
+    const parentHandle = registerSceneAsset(world, parent);
+    SceneOwner.worldSetSceneAssetResolver(world, () => ok(childHandle));
+    const r = SceneOwner.worldInstantiateScene(world, parentHandle);
+    if (!r.ok) throw new Error('instantiate failed');
+    const inst = world.get(r.value.root, SceneInstance);
+    if (!inst.ok) throw new Error('get failed');
+    expect(inst.value.mapping).toBeInstanceOf(Uint32Array);
+    if (!(inst.value.mapping instanceof Uint32Array)) return;
+    const member = inst.value.mapping[1] as unknown as number;
+    // Read-back invariant
+    const t = world.get(member as never, Transform);
+    expect(t.ok).toBe(true);
+    if (!t.ok) return;
+    expect(Array.from(t.value.pos)).toEqual([42, 0, 0]);
+    // State-map invariant
+    const stateRes = SceneOwner.worldGetSceneInstanceState(world, r.value.root);
+    if (!stateRes.ok) throw new Error('getSceneInstanceState failed');
+    expect(stateRes.value.overrides.has(1 as never)).toBe(true);
+    const fields = stateRes.value.overrides.get(1 as never);
+    expect(fields).toBeDefined();
+    expect(fields?.has('Transform:pos')).toBe(true);
+    expect(fields?.get('Transform:pos')?.value).toEqual([42, 0, 0]);
+  });
+});
+
+describe('world.setSceneOverride (w20)', () => {
+  it('writes override + readback returns the override value', () => {
+    const world = new World();
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: { pos: [1, 0, 0] } } }],
+    };
+    const handle = registerSceneAsset(world, asset);
+    const r = SceneOwner.worldInstantiateScene(world, handle);
+    if (!r.ok) throw new Error('instantiate failed');
+    const inst = world.get(r.value.root, SceneInstance);
+    if (!inst.ok) throw new Error('get failed');
+    expect(inst.value.mapping).toBeInstanceOf(Uint32Array);
+    if (!(inst.value.mapping instanceof Uint32Array)) return;
+    const member = inst.value.mapping[0] as unknown as number;
+    const sr = SceneOwner.worldSetSceneOverride(
+      world,
+      r.value.root,
+      member as never,
+      Transform,
+      'pos',
+      [99, 0, 0],
+    );
+    expect(sr.ok).toBe(true);
+    const t = world.get(member as never, Transform);
+    if (!t.ok) throw new Error('get t failed');
+    expect(Array.from(t.value.pos)).toEqual([99, 0, 0]);
+  });
+
+  it('returns scene-override-type-mismatch on bad value type', () => {
+    // Transform's fields are all arrays now; the scalar typeof guard only
+    // fires for primitive scalar fields, so exercise it via a scalar
+    // component instead.
+    const Hp = defineComponent('SceneOverrideHp', { hp: 'f32' });
+    const world = new World();
+    registerSceneComponents(world, [Hp]);
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { SceneOverrideHp: {} } }],
+    };
+    const handle = registerSceneAsset(world, asset);
+    const r = SceneOwner.worldInstantiateScene(world, handle);
+    if (!r.ok) throw new Error('instantiate failed');
+    const inst = world.get(r.value.root, SceneInstance);
+    if (!inst.ok) throw new Error('get failed');
+    const member = inst.value.mapping[0] as unknown as number;
+    // Pass a string for an f32 field
+    const sr = SceneOwner.worldSetSceneOverride(
+      world,
+      r.value.root,
+      member as never,
+      Hp,
+      'hp',
+      'oops' as unknown as number,
+    );
+    expect(sr.ok).toBe(false);
+    if (sr.ok) return;
+    const errCode = (sr.error as { code: string }).code;
+    expect(errCode).toBe('scene-override-type-mismatch');
+  });
+});
+
+describe('world.removeSceneOverride (w20)', () => {
+  it('rolls back to the source SceneAsset value', () => {
+    const world = new World();
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: { pos: [5, 0, 0] } } }],
+    };
+    const handle = registerSceneAsset(world, asset);
+    const r = SceneOwner.worldInstantiateScene(world, handle);
+    if (!r.ok) throw new Error('instantiate failed');
+    const inst = world.get(r.value.root, SceneInstance);
+    if (!inst.ok) throw new Error('get failed');
+    const member = inst.value.mapping[0] as unknown as number;
+    SceneOwner.worldSetSceneOverride(
+      world,
+      r.value.root,
+      member as never,
+      Transform,
+      'pos',
+      [100, 0, 0],
+    );
+    const rr = SceneOwner.worldRemoveSceneOverride(
+      world,
+      r.value.root,
+      member as never,
+      Transform,
+      'pos',
+    );
+    expect(rr.ok).toBe(true);
+    const t = world.get(member as never, Transform);
+    if (!t.ok) throw new Error('get failed');
+    expect(Array.from(t.value.pos)).toEqual([5, 0, 0]);
+  });
+});
+
+describe('world.detachSceneMember + reattachSceneMember (w20)', () => {
+  it('detach marks the localId; member entity stays alive; reattach unmarks', () => {
+    const world = new World();
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: {} } }],
+    };
+    const handle = registerSceneAsset(world, asset);
+    const r = SceneOwner.worldInstantiateScene(world, handle);
+    if (!r.ok) throw new Error('instantiate failed');
+    const inst = world.get(r.value.root, SceneInstance);
+    if (!inst.ok) throw new Error('get failed');
+    const member = inst.value.mapping[0] as unknown as number;
+    const dr = SceneOwner.worldDetachSceneMember(world, r.value.root, member as never);
+    expect(dr.ok).toBe(true);
+    const stateRes = SceneOwner.worldGetSceneInstanceState(world, r.value.root);
+    if (!stateRes.ok) throw new Error('getSceneInstanceState failed');
+    expect(stateRes.value.detachedLocalIds.has(0 as never)).toBe(true);
+    // Member still alive
+    expect(world.get(member as never, Transform).ok).toBe(true);
+    // Reattach
+    const rr = SceneOwner.worldReattachSceneMember(world, r.value.root, member as never);
+    expect(rr.ok).toBe(true);
+    expect(stateRes.value.detachedLocalIds.has(0 as never)).toBe(false);
+  });
+});

package/src/__tests__/zero-compression-zero-load.integration.test.ts

@@ -0,0 +1,107 @@
+// w18 — Integration: compression ratio
+//
+// AC-05 compression ratio: compress a programmatic ~3.2MB f32 vertex
+//       fixture with zstd, assert compressedSize / originalSize <= 0.70
+//       (>= 30% reduction). Fixture is programmatic f32 array mimicking real
+//       mesh bin layout (28B header + Float32Array vertices + Uint16Array
+//       indices + JSON tail).
+//
+// TDD-RED before w20 — the mesh default flip had not happened yet.
+//
+// Plan decisions:
+//   AC-05: mesh .bin ≥30% compression ratio
+//   R5: ratio is interval inference, assert >= 0.30 lower bound
+//   D-10: all fixture data programmatic
+
+import { describe, expect, it } from 'vitest';
+
+describe('w18: zero-compression zero-decoder loading + compression ratio', () => {
+  /**
+   * AC-05 compression ratio: compress a ~3.2MB vertex payload with zstd,
+   * verify >= 30% reduction.
+   *
+   * Not TDD-red — this is a direct codec compressZstd call against a
+   * synthetic fixture, and the codec is already complete from M1.
+   */
+  it('AC-05: zstd compression ratio >= 30% for ~3.2MB f32 vertex fixture', async () => {
+    const { compressZstd } = await import('@forgeax/engine-codec/encode');
+
+    // Build a realistic mesh bin payload simulating a ~100K vertex mesh.
+    // 28B header + 100K vertices * 12 floats/vertex * 4 bytes/float
+    // = 28 + 4,800,000 = ~4.8MB. We use 80K vertices to stay near 3.2MB
+    // of vertex data.
+    const vertexCount = 80000;
+    const floatsPerVertex = 12;
+    const vlen = vertexCount * floatsPerVertex; // 960000
+    const ilen = 120000; // roughly 1.5x vertex count for indices
+    const iwidth = 2;
+    const jsonTail =
+      '{"submeshes":[{"indexOffset":0,"indexCount":120000,"vertexCount":960000,"topology":"triangle-list"}],"aabb":[-1,-1,-1,1,1,1]}';
+    const jsonBytes = new TextEncoder().encode(jsonTail);
+
+    const header = new ArrayBuffer(28);
+    const dv = new DataView(header);
+    dv.setUint32(0, 2, true);
+    dv.setUint32(4, 1, true);
+    dv.setUint32(8, 12, true);
+    dv.setUint32(12, vlen, true);
+    dv.setUint32(16, ilen, true);
+    dv.setUint32(20, iwidth, true);
+    dv.setUint32(24, jsonBytes.length, true);
+
+    const vertices = new Float32Array(vlen);
+    for (let i = 0; i < vertexCount; i++) {
+      const b = i * floatsPerVertex;
+      // position (pseudo-random pattern mimicking real mesh data)
+      vertices[b + 0] = Math.sin(i * 0.1) * 10;
+      vertices[b + 1] = Math.cos(i * 0.1) * 10;
+      vertices[b + 2] = Math.sin(i * 0.05) * 5;
+      // normal (unit-lengthish)
+      const nx = Math.sin(i * 0.07);
+      const ny = 0.5 + Math.cos(i * 0.07) * 0.5;
+      const nz = Math.cos(i * 0.03);
+      const len = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+      vertices[b + 3] = nx / len;
+      vertices[b + 4] = ny / len;
+      vertices[b + 5] = nz / len;
+      // uv
+      vertices[b + 6] = (i % 100) / 100;
+      vertices[b + 7] = Math.floor(i / 100) / 100;
+      // tangent
+      vertices[b + 8] = 1;
+      vertices[b + 9] = 0;
+      vertices[b + 10] = 0;
+      vertices[b + 11] = 1;
+    }
+
+    const indices = new Uint16Array(ilen);
+    for (let i = 0; i < ilen; i++) {
+      indices[i] = i % vertexCount;
+    }
+
+    const totalSize = 28 + vlen * 4 + ilen * iwidth + jsonBytes.length;
+    const meshBin = new Uint8Array(totalSize);
+    let offset = 0;
+    meshBin.set(new Uint8Array(header), offset);
+    offset += 28;
+    meshBin.set(new Uint8Array(vertices.buffer, vertices.byteOffset, vertices.byteLength), offset);
+    offset += vlen * 4;
+    meshBin.set(new Uint8Array(indices.buffer, indices.byteOffset, indices.byteLength), offset);
+    offset += ilen * iwidth;
+    meshBin.set(jsonBytes, offset);
+
+    const originalSize = meshBin.length;
+    // Should be roughly: 28 + 3,840,000 + 240,000 + ~100 = ~4,080,128 bytes (~4MB)
+    expect(originalSize).toBeGreaterThan(3_000_000); // sanity: > 3MB
+
+    const compRes = await compressZstd(meshBin);
+    expect(compRes.ok).toBe(true);
+    if (!compRes.ok) return;
+
+    const compressedSize = compRes.value.length;
+    const ratio = compressedSize / originalSize;
+
+    // AC-05: >= 30% reduction (compressed <= 70% of original)
+    expect(ratio).toBeLessThanOrEqual(0.7);
+  });
+});

package/src/asset-contributions.ts

@@ -0,0 +1,48 @@
+import { animationClipContribution, animationGraphContribution } from '@forgeax/engine-animation';
+import { audioContribution } from '@forgeax/engine-audio';
+import { fontContribution } from '@forgeax/engine-font';
+import { meshAssetContribution } from '@forgeax/engine-geometry';
+import { tilesetContribution, videoContribution } from '@forgeax/engine-graphics-extras';
+import { equirectContribution, textureContribution } from '@forgeax/engine-image';
+import {
+  materialContribution,
+  renderPipelineContribution,
+  samplerContribution,
+} from '@forgeax/engine-render';
+import { sceneAssetContribution } from '@forgeax/engine-scene';
+import { skeletonContribution, skinContribution } from '@forgeax/engine-skinning';
+import type { AssetDecoderContributionRef } from '@forgeax/engine-types';
+import { particleEffectContribution } from '@forgeax/engine-vfx';
+
+/**
+ * The built-in decoder set assembled by the host/runtime boundary.
+ *
+ * Each entry remains owned by its domain package; this list is only the one
+ * default lease assembly for an App realm. A caller-provided contribution for
+ * a built-in kind replaces that default entry for the current realm.
+ */
+const typedDefaultAssetDecoderContributions = [
+  meshAssetContribution,
+  materialContribution,
+  sceneAssetContribution,
+  textureContribution,
+  equirectContribution,
+  samplerContribution,
+  fontContribution,
+  renderPipelineContribution,
+  tilesetContribution,
+  videoContribution,
+  skeletonContribution,
+  skinContribution,
+  animationClipContribution,
+  animationGraphContribution,
+  audioContribution,
+  particleEffectContribution,
+] as const;
+
+// The registry installation seam intentionally erases the payload type while
+// it stores heterogeneous owner contributions. Each owner contribution above
+// remains typed at its source and is checked again by its decoder.
+export const defaultAssetDecoderContributions = Object.freeze(
+  typedDefaultAssetDecoderContributions as unknown as readonly AssetDecoderContributionRef[],
+);

package/src/backend-selection.ts

@@ -0,0 +1,69 @@
+import type { RendererOptions } from '@forgeax/engine-render';
+import type { RhiBackendPack } from '@forgeax/engine-render/internal/construct-renderer';
+import { err, ok, RhiError } from '@forgeax/engine-rhi';
+import * as rhiWebgpu from '@forgeax/engine-rhi-webgpu';
+
+export function loadRhiPack(
+  mod: Record<string, unknown>,
+  instrumentation?: RhiBackendPack['instrumentation'],
+): RhiBackendPack {
+  const rhi = mod.rhi as unknown as RhiBackendPack['rhi'];
+  const createShaderModule = mod.createShaderModule as
+    | RhiBackendPack['createShaderModule']
+    | undefined;
+  const translateErrorEventToRhiError = mod.translateErrorEventToRhiError as
+    | RhiBackendPack['translateErrorEventToRhiError']
+    | undefined;
+  const rawDeviceAccessor = mod._internal_getRawDevice as unknown as
+    | RhiBackendPack['_internal_getRawDevice']
+    | undefined;
+  const backendInstrumentation = mod.instrumentation as
+    | RhiBackendPack['instrumentation']
+    | undefined;
+  const pack: RhiBackendPack = {
+    rhi,
+    ...(createShaderModule === undefined ? {} : { createShaderModule }),
+    ...(translateErrorEventToRhiError === undefined ? {} : { translateErrorEventToRhiError }),
+    ...(rawDeviceAccessor === undefined ? {} : { _internal_getRawDevice: rawDeviceAccessor }),
+  };
+  const resolvedInstrumentation = instrumentation ?? backendInstrumentation;
+  return resolvedInstrumentation === undefined
+    ? pack
+    : { ...pack, instrumentation: resolvedInstrumentation };
+}
+
+/** Selects one backend pack; render receives only this typed owner contract. */
+export async function loadBackendPack(
+  options: RendererOptions | undefined,
+  preferWgpu = false,
+): Promise<
+  | { readonly ok: true; readonly value: RhiBackendPack }
+  | { readonly ok: false; readonly error: RhiError }
+> {
+  const explicit = options?.rhi;
+  if (explicit !== undefined && explicit !== null) {
+    return ok(loadRhiPack({ rhi: explicit, ...(explicit as object) }, options?.rhiInstrumentation));
+  }
+  const nav =
+    typeof globalThis === 'undefined'
+      ? undefined
+      : (globalThis as { navigator?: { gpu?: unknown } }).navigator;
+  if (!preferWgpu && nav?.gpu !== undefined && nav.gpu !== null) {
+    return ok(
+      loadRhiPack(rhiWebgpu as unknown as Record<string, unknown>, options?.rhiInstrumentation),
+    );
+  }
+  try {
+    const mod = (await import('@forgeax/engine-rhi-wgpu')) as Record<string, unknown>;
+    await (mod.ensureReady as () => Promise<unknown>)();
+    return ok(loadRhiPack(mod, options?.rhiInstrumentation));
+  } catch (cause) {
+    return err(
+      new RhiError({
+        code: 'rhi-not-available',
+        expected: 'a usable RHI backend is available',
+        hint: `failed to load wgpu backend: ${String(cause)}`,
+      }),
+    );
+  }
+}