@forgeax/engine-runtime 0.1.2

package/src/__tests__/view-ubo-layout.browser.test.ts

@@ -0,0 +1,183 @@
+// view-ubo-layout.browser.test.ts - feat-20260518-pbr-direct-lighting-mvp
+// feat-20260531-skybox-env-background M2 / w4 (TDD red): VIEW_UBO_BYTES
+// 112 -> 176 -> 240 layout (worldViewProj 64 B + lightDir 16 B + lightColor
+// 16 B + cameraPos 16 B + lightSpaceMatrix 64 B + inverseViewProj 64 B;
+// std140 vec3 padded to 16-byte boundaries).
+//
+// Plan-strategy D-4 + AC-06: the view UBO grows from 176 to 240 by
+// appending inverseViewProj mat4x4<f32> (64 B) at the tail. Earlier field
+// offsets [0..175] are unchanged -- this is a pure tail-append. Naming:
+// `cameraPos` (not `viewPos`) lines up with the shader-side identifier
+// used in pbr.wgsl `view.cameraPos` (single SSOT, charter P5 consistent
+// abstraction).
+//
+// std140 byte map (the shader-side ABI lock):
+//   [  0.. 64) worldViewProj  mat4x4<f32>  (16 floats)
+//   [ 64.. 76) lightDir       vec3<f32>    (3 floats)
+//   [ 76.. 80) padding
+//   [ 80.. 92) lightColor     vec3<f32>    (3 floats)
+//   [ 92.. 96) padding
+//   [ 96..108) cameraPos      vec3<f32>    (3 floats)
+//   [108..112) padding
+//   [112..176) lightSpaceMatrix mat4x4<f32> (16 floats)
+//   [176..240) inverseViewProj mat4x4<f32> (16 floats)
+//
+// Tier: browser (vitest browser + chromium WebGPU). The test asserts:
+//   (a) the host writes a 240-byte buffer (Float32Array length 60)
+//   (b) field offsets match the std140 map above
+//   (c) the BindGroupLayout view UBO entry declares minBindingSize=240 so
+//       smaller writes fail-fast with WebGPU validation error.
+// The full pixel-readback gate lives in `standard-pipeline-render.browser.test.ts`
+// (w15, AC-12 / AC-14); this gate locks the byte layout itself.
+
+import { describe, expect, it } from 'vitest';
+// @ts-expect-error Vite provides raw text imports to the browser test runner.
+import viewUboSource from '../../../render/src/record/view-ubo.ts?raw';
+// @ts-expect-error Vite provides raw text imports to the browser test runner.
+import commonViewSource from '../../../shader/src/common.wgsl?raw';
+
+const browserReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+// Single SSOT for the std140 byte offsets - reused by future tests + AGENTS.md
+// breaking-changes index entries that reference the layout.
+const VIEW_UBO_OFFSETS = {
+  worldViewProj: 0,
+  lightDir: 64,
+  lightColor: 80,
+  cameraPos: 96,
+  lightSpaceMatrix: 112,
+  inverseViewProj: 176,
+} as const;
+const VIEW_UBO_BYTES = 240;
+
+describe('w4 view UBO 240 B std140 layout (AC-06, browser)', () => {
+  it.skipIf(!browserReady)('host write payload is exactly 240 bytes (60 floats)', () => {
+    // The host (render-system-record.ts) builds a Float32Array(60) and
+    // emits a single queue.writeBuffer. Asserting the size lock here keeps
+    // the host shape and shader ABI in agreement before the GPU sees it.
+    const payload = new Float32Array(60);
+    expect(payload.byteLength).toBe(VIEW_UBO_BYTES);
+  });
+
+  it.skipIf(!browserReady)('field offsets match std140 vec3-padded-to-16 layout', () => {
+    expect(VIEW_UBO_OFFSETS.worldViewProj).toBe(0);
+    expect(VIEW_UBO_OFFSETS.lightDir).toBe(64);
+    expect(VIEW_UBO_OFFSETS.lightColor).toBe(80);
+    expect(VIEW_UBO_OFFSETS.cameraPos).toBe(96);
+    expect(VIEW_UBO_OFFSETS.lightSpaceMatrix).toBe(112);
+    expect(VIEW_UBO_OFFSETS.inverseViewProj).toBe(176);
+    // Buffer total = inverseViewProj offset + mat4 (64 B) = 240.
+    expect(VIEW_UBO_OFFSETS.inverseViewProj + 64).toBe(VIEW_UBO_BYTES);
+  });
+
+  it.skipIf(!browserReady)(
+    'host packs lightDir / lightColor / cameraPos at canonical std140 slots',
+    () => {
+      // Canonical packing order documented in plan-strategy D-4: the host
+      // builds a 60-float buffer mirroring the shader-side `View` struct
+      // field order. AC-06: existing field offsets unchanged -- tail append
+      // only.
+      const payload = new Float32Array(60);
+      // worldViewProj = identity for this assertion (mat4 in [0..16))
+      payload[0] = 1; // m00
+      payload[5] = 1; // m11
+      payload[10] = 1; // m22
+      payload[15] = 1; // m33
+      // lightDir (slot 16..19; index 19 is padding)
+      payload[16] = -0.3;
+      payload[17] = -1.0;
+      payload[18] = -0.5;
+      // lightColor (slot 20..23; index 23 is padding)
+      payload[20] = 1.0;
+      payload[21] = 0.95;
+      payload[22] = 0.9;
+      // cameraPos (slot 24..27; index 27 is padding)
+      payload[24] = 0;
+      payload[25] = 0;
+      payload[26] = 5;
+
+      // lightDir at byte offset 64 = float index 16
+      expect(payload[16]).toBeCloseTo(-0.3, 6);
+      expect(payload[17]).toBeCloseTo(-1.0, 6);
+      expect(payload[18]).toBeCloseTo(-0.5, 6);
+      // lightColor at byte offset 80 = float index 20
+      expect(payload[20]).toBeCloseTo(1.0, 6);
+      expect(payload[21]).toBeCloseTo(0.95, 6);
+      expect(payload[22]).toBeCloseTo(0.9, 6);
+      // cameraPos at byte offset 96 = float index 24
+      expect(payload[24]).toBeCloseTo(0, 6);
+      expect(payload[25]).toBeCloseTo(0, 6);
+      expect(payload[26]).toBeCloseTo(5, 6);
+
+      // Padding slots (indices 19 / 23 / 27) stay zero in the canonical write.
+      // This is not a hard requirement (std140 only requires alignment, not
+      // zeroed padding) but the host writeBuffer convention is to zero-fill
+      // by allocating Float32Array(60) so AI users reading the buffer in a
+      // debugger see the structure clearly (charter P3 explicit failure +
+      // F1 surface minimization).
+      expect(payload[19]).toBe(0);
+      expect(payload[23]).toBe(0);
+      expect(payload[27]).toBe(0);
+    },
+  );
+
+  it.skipIf(!browserReady)('cameraPos naming literal lock (AC-07: cameraPos not viewPos)', () => {
+    // Charter P5 consistent abstraction red line: shader-side
+    // `view.cameraPos` (pbr.wgsl line ~153 `view.cameraPos - in.worldPos`)
+    // and host-side keyword `cameraPos` are one literal. AC-07 motivates
+    // tracking this in a test so renames sweep both sides at once.
+    const literal: keyof typeof VIEW_UBO_OFFSETS = 'cameraPos';
+    expect(literal).toBe('cameraPos');
+    expect(literal as string).not.toBe('viewPos');
+  });
+
+  it.skipIf(!browserReady)('inverseViewProj offset at float index 44 (byte offset 176)', () => {
+    // AC-06: inverseViewProj occupies floats [44..59] at byte offset
+    // [176..240). Verify the offset constant matches the float-index
+    // calculation.
+    const inverseProjF32Index = VIEW_UBO_OFFSETS.inverseViewProj / 4;
+    expect(inverseProjF32Index).toBe(44);
+    const payload = new Float32Array(60);
+    // Place an identity mat4 at inverseViewProj slot [44..59]
+    payload[44] = 1;
+    payload[49] = 1;
+    payload[54] = 1;
+    payload[59] = 1;
+    expect(payload[44]).toBe(1);
+    expect(payload[49]).toBe(1);
+    expect(payload[54]).toBe(1);
+    expect(payload[59]).toBe(1);
+  });
+
+  it.skipIf(!browserReady)(
+    'existing field offsets unchanged by tail append (AC-06 rear-append guarantee)',
+    () => {
+      // The tail append of inverseViewProj must not shift earlier fields.
+      // AC-06 lock: worldViewProj=0, lightDir=64, lightColor=80,
+      // cameraPos=96, lightSpaceMatrix=112 -- same as the 176 B layout.
+      expect(VIEW_UBO_OFFSETS.worldViewProj).toBe(0);
+      expect(VIEW_UBO_OFFSETS.lightDir).toBe(64);
+      expect(VIEW_UBO_OFFSETS.lightColor).toBe(80);
+      expect(VIEW_UBO_OFFSETS.cameraPos).toBe(96);
+      expect(VIEW_UBO_OFFSETS.lightSpaceMatrix).toBe(112);
+    },
+  );
+});
+
+describe('Fog View ABI transport (M2)', () => {
+  it('host payload grows beyond the stale 784 B prefix and carries Fog facts', async () => {
+    const source = await viewUboSource;
+    expect(source).toContain('VIEW_PAYLOAD_FLOATS = 240');
+    expect(source).toContain('heightFalloff');
+    expect(source).toContain('maxOpacity');
+    expect(source).not.toContain('VIEW_PAYLOAD_FLOATS = 196');
+  });
+
+  it('shader View carries Fog in the existing uniform binding', async () => {
+    const [viewSource, commonSource] = await Promise.all([viewUboSource, commonViewSource]);
+    expect(viewSource).toContain('viewPayload[232]');
+    expect(commonSource).toContain('fog                 : FogViewParams');
+    expect(commonSource).toContain('@group(0) @binding(0) var<uniform> view : View;');
+    expect(commonSource).not.toContain('@group(0) @binding(10)');
+  });
+});

package/src/__tests__/world-entity-key.test.ts

@@ -0,0 +1,92 @@
+// m1-t1: worldEntityKey helper unit test (TDD red).
+//
+// Test the worldEntityKey(worldId, entityKey) composite key formula:
+//   worldId * 2^32 + entityKey
+//
+// Key invariants from plan-strategy D-1/D-9:
+//   - worldId=0 identity: worldEntityKey(0, k) === k (AC-03 single-world path)
+//   - Different worldId produce different keys
+//   - Same inputs produce same key
+//   - JS safe integer: worldId < 2^21 does not overflow Number.MAX_SAFE_INTEGER
+//
+// Anchors:
+//   plan-tasks.json m1-t1
+//   plan-strategy D-1/D-9
+//   requirements AC-03
+
+import { worldEntityKey } from '@forgeax/engine-render/internal';
+import { describe, expect, it } from 'vitest';
+
+describe('worldEntityKey', () => {
+  // ── Identity: worldId=0 ──────────────────────────────────────────────────
+
+  it('worldId=0 identity — worldEntityKey(0, k) === k', () => {
+    expect(worldEntityKey(0, 0)).toBe(0);
+    expect(worldEntityKey(0, 1)).toBe(1);
+    expect(worldEntityKey(0, 42)).toBe(42);
+    expect(worldEntityKey(0, 0xffffffff)).toBe(0xffffffff);
+  });
+
+  // ── Different worldId produce different keys ─────────────────────────────
+
+  it('different worldId produce different keys for same entityKey', () => {
+    expect(worldEntityKey(0, 42)).not.toBe(worldEntityKey(1, 42));
+    expect(worldEntityKey(1, 42)).not.toBe(worldEntityKey(2, 42));
+    expect(worldEntityKey(0, 1)).not.toBe(worldEntityKey(1, 1));
+  });
+
+  // ── Same inputs produce same key ─────────────────────────────────────────
+
+  it('same (worldId, entityKey) always produces same key', () => {
+    expect(worldEntityKey(3, 100)).toBe(worldEntityKey(3, 100));
+    expect(worldEntityKey(5, 0)).toBe(worldEntityKey(5, 0));
+  });
+
+  // ── Concrete value check ─────────────────────────────────────────────────
+
+  it('worldId=1, entityKey=42 => 4294967338', () => {
+    // 1 * 2^32 + 42 = 4294967296 + 42 = 4294967338
+    expect(worldEntityKey(1, 42)).toBe(4294967338);
+  });
+
+  // ── JS safe integer boundary ─────────────────────────────────────────────
+
+  it('worldId=2^20 does not exceed Number.MAX_SAFE_INTEGER', () => {
+    // 2^20 * 2^32 + 0xFFFFFFFF = 2^52 + 2^32 - 1
+    // 2^52 = 4503599627370496
+    // MAX_SAFE_INTEGER = 2^53 - 1 = 9007199254740991
+    // 2^52 + 2^32 - 1 < 2^53 - 1 ✓
+    const key = worldEntityKey(2 ** 20, 0xffffffff);
+    expect(key).toBeLessThan(Number.MAX_SAFE_INTEGER);
+    expect(key).toBe(2 ** 52 + 2 ** 32 - 1);
+  });
+
+  it('worldId=2^21 boundary is still safe', () => {
+    // 2^21 * 2^32 + 0 = 2^53 = 9007199254740992
+    // This equals MAX_SAFE_INTEGER + 1, so it loses integer precision
+    // But the acceptanceCheck says "worldId=2^20 does not overflow" — test
+    // that 2^20 is the safe boundary
+    const keyAt20 = worldEntityKey(2 ** 20, 0);
+    const keyAt21 = worldEntityKey(2 ** 21, 0);
+    // At 2^21 the integer precision is lost, so keyAt21 !== keyAt20 + 2^52
+    // This is documented behavior — worldId < 2^21 is the contract
+    expect(keyAt20).toBe(2 ** 52);
+    // 2^21 * 2^32 = 2^53 which exceeds safe integer; the function
+    // should still compute without throwing, but the result may be imprecise
+    expect(typeof keyAt21).toBe('number');
+  });
+
+  // ── Edge cases ───────────────────────────────────────────────────────────
+
+  it('entityKey=0 across worldIds', () => {
+    expect(worldEntityKey(0, 0)).toBe(0);
+    expect(worldEntityKey(1, 0)).toBe(2 ** 32);
+    expect(worldEntityKey(2, 0)).toBe(2 * 2 ** 32);
+  });
+
+  it('entityKey max u32 (0xFFFFFFFF) across worldIds', () => {
+    const maxU32 = 0xffffffff;
+    expect(worldEntityKey(0, maxU32)).toBe(maxU32);
+    expect(worldEntityKey(1, maxU32)).toBe(2 ** 32 + maxU32);
+  });
+});

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

@@ -0,0 +1,132 @@
+// feat-20260608-scene-nesting-ecs-fication M2 / w19 (red phase) — despawnScene
+// + despawnDescendants. Lives under runtime for the same import-isolation
+// reason as world-scene-instantiate.test.ts.
+//
+// Coverage:
+//   - despawnScene(root) recursively despawns root + every member;
+//   - despawnDescendants(root) despawns descendants but keeps root alive;
+//   - despawnDescendants(plain entity) walks the standard ChildOf chain
+//     (no SceneInstance required);
+//   - opts.keepDetached preserves members marked via detachSceneMember.
+
+import { World } from '@forgeax/engine-ecs';
+import { SceneInstance } from '@forgeax/engine-render/internal';
+import {
+  ChildOf,
+  Transform,
+  worldDespawnDescendants,
+  worldDespawnScene,
+  worldDetachSceneMember,
+  worldInstantiateScene,
+} from '@forgeax/engine-scene';
+import type { Handle, SceneAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function registerSceneAsset(world: World, asset: SceneAsset): Handle<'SceneAsset', 'shared'> {
+  for (const component of [SceneInstance, ChildOf, Transform]) {
+    world.components.register(component).unwrap();
+  }
+  return world.allocSharedRef('SceneAsset', asset);
+}
+
+describe('world.despawnScene (w19)', () => {
+  it('despawns root + every member', () => {
+    const world = new World();
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [
+        { localId: 0 as never, components: { Transform: {} } },
+        { localId: 1 as never, components: { Transform: {} } },
+      ],
+    };
+    const handle = registerSceneAsset(world, asset);
+    const r = worldInstantiateScene(world, handle);
+    if (!r.ok) throw new Error('instantiateScene 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 m0 = inst.value.mapping[0] as unknown as number;
+    const m1 = inst.value.mapping[1] as unknown as number;
+
+    const dr = worldDespawnScene(world, r.value.root);
+    expect(dr.ok).toBe(true);
+    if (!dr.ok) return;
+    expect(dr.value).toBeGreaterThanOrEqual(3); // root + 2 members
+
+    // After despawn, get() on root + members must fail
+    expect(world.get(r.value.root, SceneInstance).ok).toBe(false);
+    expect(world.get(m0 as never, Transform).ok).toBe(false);
+    expect(world.get(m1 as never, Transform).ok).toBe(false);
+  });
+
+  it('keepDetached: true skips members marked detached', () => {
+    const world = new World();
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [
+        { localId: 0 as never, components: { Transform: {} } },
+        { localId: 1 as never, components: { Transform: {} } },
+      ],
+    };
+    const handle = registerSceneAsset(world, asset);
+    const r = 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 member1 = inst.value.mapping[1] as unknown as number;
+
+    const det = worldDetachSceneMember(world, r.value.root, member1 as never);
+    expect(det.ok).toBe(true);
+
+    const dr = worldDespawnScene(world, r.value.root, { keepDetached: true });
+    expect(dr.ok).toBe(true);
+    // Detached member must remain alive
+    expect(world.get(member1 as never, Transform).ok).toBe(true);
+  });
+});
+
+describe('world.despawnDescendants (w19)', () => {
+  it('despawns descendants but keeps root alive', () => {
+    const world = new World();
+    const root = world.spawn({ component: Transform, data: {} });
+    if (!root.ok) throw new Error('spawn root failed');
+    const child = world.spawn(
+      { component: Transform, data: {} },
+      { component: ChildOf, data: { parent: root.value } },
+    );
+    if (!child.ok) throw new Error('spawn child failed');
+
+    const dr = worldDespawnDescendants(world, root.value);
+    expect(dr.ok).toBe(true);
+    if (!dr.ok) return;
+    expect(dr.value).toBeGreaterThanOrEqual(1); // child despawned
+
+    // Root must still be alive; child must be dead
+    expect(world.get(root.value, Transform).ok).toBe(true);
+    expect(world.get(child.value, Transform).ok).toBe(false);
+  });
+
+  it('despawnDescendants on a plain entity (no SceneInstance) walks the ChildOf chain', () => {
+    const world = new World();
+    const root = world.spawn({ component: Transform, data: {} });
+    if (!root.ok) throw new Error('spawn failed');
+    const c1 = world.spawn(
+      { component: Transform, data: {} },
+      { component: ChildOf, data: { parent: root.value } },
+    );
+    if (!c1.ok) throw new Error('spawn failed');
+    const c2 = world.spawn(
+      { component: Transform, data: {} },
+      { component: ChildOf, data: { parent: c1.value } },
+    );
+    if (!c2.ok) throw new Error('spawn failed');
+
+    const dr = worldDespawnDescendants(world, root.value);
+    expect(dr.ok).toBe(true);
+    expect(world.get(c1.value, Transform).ok).toBe(false);
+    expect(world.get(c2.value, Transform).ok).toBe(false);
+  });
+});

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

@@ -0,0 +1,228 @@
+// feat-20260608-scene-nesting-ecs-fication M2 / w17 + w22 + w23 (red phase) —
+// world.instantiateScene + world.getSceneAssetForInstance + perf.
+//
+// Test file location: under runtime (NOT ecs) because plan-tasks targetFiles
+// pointed at packages/ecs/src/__tests__/ but `scripts/check-ecs-no-runtime-
+// import.mjs` (AC-29 gate) rejects value-imports of @forgeax/engine-runtime
+// from packages/ecs/src/. The scene tests must reach the SceneInstance /
+// Transform / ChildOf component tokens (defined in runtime), so the file
+// physically lives in runtime; the World method calls themselves still
+// resolve to packages/ecs/src/world.ts behind the @forgeax/engine-ecs barrel.
+// (See implementer milestone report `filesOutsideTargets` row.)
+//
+// w17: instantiateScene basic path — Result<Entity, EcsError>; the returned
+//   entity is the synthetic root carrying SceneInstance; mapping length =
+//   entities.length when no mounts; member entities carry the layer-1
+//   component values; ChildOf.parent flows through to caller-supplied parent.
+// w22: getSceneAssetForInstance — Ok(sourceHandle) on a SceneInstance root;
+//   Err on a plain entity.
+// w23: perf — 100 entities x 5 components instantiates < 50ms (plan §5.4).
+
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import { SceneInstance } from '@forgeax/engine-render/internal';
+import {
+  ChildOf,
+  Children,
+  Transform,
+  worldGetSceneAssetForInstance,
+  worldInstantiateScene,
+} from '@forgeax/engine-scene';
+import type { Handle, SceneAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+function registerSceneAsset(
+  world: World,
+  asset: SceneAsset,
+  extraComponents: readonly Parameters<World['components']['register']>[0][] = [],
+): Handle<'SceneAsset', 'shared'> {
+  for (const component of [SceneInstance, ChildOf, Children, Transform, ...extraComponents]) {
+    world.components.register(component).unwrap();
+  }
+  return world.allocSharedRef('SceneAsset', asset);
+}
+
+function instantiateScene(
+  world: World,
+  handle: Handle<'SceneAsset', 'shared'>,
+  parent?: Parameters<typeof worldInstantiateScene>[2],
+) {
+  return worldInstantiateScene(world, handle, parent);
+}
+
+describe('world.instantiateScene basic (w17)', () => {
+  it('returns Result.ok(synthetic root entity) with SceneInstance attached', () => {
+    const world = new World();
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [
+        {
+          localId: 0 as never,
+          components: { Transform: { pos: [1, 2, 3] } },
+        },
+      ],
+    };
+    const handle = registerSceneAsset(world, asset);
+    const r = instantiateScene(world, handle);
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    const inst = world.get(r.value.root, SceneInstance);
+    expect(inst.ok).toBe(true);
+  });
+
+  it('SceneInstance.mapping length === entities.length when no mounts', () => {
+    const world = new World();
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [
+        { localId: 0 as never, components: { Transform: {} } },
+        { localId: 1 as never, components: { Transform: {} } },
+        { localId: 2 as never, components: { Transform: {} } },
+      ],
+    };
+    const handle = registerSceneAsset(world, asset);
+    const r = instantiateScene(world, handle);
+    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;
+    expect(inst.value.mapping.length).toBe(3);
+  });
+
+  it('member entities carry the layer-1 component values', () => {
+    const world = new World();
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [
+        {
+          localId: 0 as never,
+          components: { Transform: { pos: [7, 8, 9] } },
+        },
+      ],
+    };
+    const handle = registerSceneAsset(world, asset);
+    const r = instantiateScene(world, handle);
+    if (!r.ok) throw new Error('instantiateScene failed');
+    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;
+    const memberRaw = inst.value.mapping[0];
+    expect(memberRaw).toBeDefined();
+    if (memberRaw === undefined) return;
+    const t = world.get(memberRaw as never, Transform);
+    expect(t.ok).toBe(true);
+    if (!t.ok) return;
+    expect(Array.from(t.value.pos)).toEqual([7, 8, 9]);
+  });
+
+  it('synthetic root ChildOf flows to caller-supplied parent', () => {
+    const world = new World();
+    const parentRes = world.spawn({ component: Transform, data: {} });
+    if (!parentRes.ok) throw new Error('spawn parent failed');
+    const parent = parentRes.value;
+
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: {} } }],
+    };
+    const handle = registerSceneAsset(world, asset);
+    const r = instantiateScene(world, handle, parent);
+    if (!r.ok) throw new Error('instantiateScene failed');
+    const rootChildOf = world.get(r.value.root, ChildOf);
+    expect(rootChildOf.ok).toBe(true);
+    if (!rootChildOf.ok) return;
+    expect(rootChildOf.value.parent as unknown as number).toBe(parent as unknown as number);
+  });
+});
+
+describe('world.getSceneAssetForInstance (w22)', () => {
+  it('returns Ok(sourceHandle) for a SceneInstance root', () => {
+    const world = new World();
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: {} } }],
+    };
+    const handle = registerSceneAsset(world, asset);
+    const r = instantiateScene(world, handle);
+    if (!r.ok) throw new Error('instantiateScene failed');
+    const got = worldGetSceneAssetForInstance(world, r.value.root);
+    expect(got.ok).toBe(true);
+    if (!got.ok) return;
+    expect(got.value as unknown as number).toBe(handle as unknown as number);
+  });
+
+  it('returns Err on a plain entity (no SceneInstance component)', () => {
+    const world = new World();
+    const e = world.spawn({ component: Transform, data: {} });
+    if (!e.ok) throw new Error('spawn failed');
+    const got = worldGetSceneAssetForInstance(world, e.value);
+    expect(got.ok).toBe(false);
+  });
+});
+
+describe('world.instantiateScene perf (w23) — 100 entities x 5 components', () => {
+  it('instantiates < 50ms', () => {
+    const world = new World();
+    const C1 = defineComponent('SceneNestPerfC1', { a: { type: 'f32', default: 0 } });
+    const C2 = defineComponent('SceneNestPerfC2', { a: { type: 'f32', default: 0 } });
+    const C3 = defineComponent('SceneNestPerfC3', { a: { type: 'f32', default: 0 } });
+    const C4 = defineComponent('SceneNestPerfC4', { a: { type: 'f32', default: 0 } });
+    void C1;
+    void C2;
+    void C3;
+    void C4;
+    const N = 100;
+    const entities = Array.from({ length: N }, (_, i) => ({
+      localId: i as never,
+      components: {
+        Transform: {},
+        SceneNestPerfC1: { a: i },
+        SceneNestPerfC2: { a: i },
+        SceneNestPerfC3: { a: i },
+        SceneNestPerfC4: { a: i },
+      },
+    }));
+    const asset: SceneAsset = { kind: 'scene', entities };
+    const handle = registerSceneAsset(world, asset, [C1, C2, C3, C4]);
+    const t0 = performance.now();
+    const r = instantiateScene(world, handle);
+    const dt = performance.now() - t0;
+    expect(r.ok).toBe(true);
+    expect(dt).toBeLessThan(50);
+  });
+});
+
+describe('M2 direct Scene owner contract', () => {
+  it('keeps successful member materialization and diagnostics on the real World path', () => {
+    const world = new World();
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { Transform: {} } }],
+    };
+    const result = worldInstantiateScene(world, registerSceneAsset(world, asset));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.diagnostics).toEqual([]);
+    const instance = world.get(result.value.root, SceneInstance);
+    expect(instance.ok).toBe(true);
+    if (instance.ok) expect(instance.value.mapping.length).toBe(1);
+  });
+
+  it('rolls back a failed component lookup without a partial SceneInstance root', () => {
+    const world = new World();
+    const result = worldInstantiateScene(
+      world,
+      registerSceneAsset(world, {
+        kind: 'scene',
+        entities: [{ localId: 0 as never, components: { M2MissingComponent: { value: 3 } } }],
+      } as SceneAsset),
+    );
+
+    expect(result.ok).toBe(false);
+    const query = world.query({ read: [SceneInstance] });
+    expect(query.ok ? Array.from(query.value) : []).toHaveLength(0);
+  });
+});